mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-23 08:23:12 +09:00
Compare commits
208
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
bbcb64d411 | ||
|
|
43abe3bb2b | ||
|
|
38cfd3d08c | ||
|
|
95f808a02f | ||
|
|
0190394a99 | ||
|
|
d11afb8742 | ||
|
|
1a016372c1 | ||
|
|
9dd5b48056 | ||
|
|
834f8472df | ||
|
|
af97b1b789 | ||
|
|
677679ac26 | ||
|
|
3c03574106 | ||
|
|
fb93962972 | ||
|
|
2a7a333b95 | ||
|
|
53ddcb1d27 | ||
|
|
555f444447 | ||
|
|
a6b44e78d6 | ||
|
|
8865038af5 | ||
|
|
f338c5fd91 | ||
|
|
bee6714ff8 | ||
|
|
ef3b4cb8fc | ||
|
|
cd2933417a | ||
|
|
bd912a8fd4 | ||
|
|
86befd1231 | ||
|
|
73d70cbc91 | ||
|
|
516dc1b945 | ||
|
|
079340e5dd | ||
|
|
565e931a96 | ||
|
|
7a2aade25b | ||
|
|
2bba4a8ccd | ||
|
|
c03666e749 | ||
|
|
3ca203c753 | ||
|
|
e1ffb848b1 | ||
|
|
fcf858023e | ||
|
|
faf214e2a1 | ||
|
|
628e59bf2c | ||
|
|
33817bbe42 | ||
|
|
8e01a96df9 | ||
|
|
8692ea3941 | ||
|
|
a49841f3fc | ||
|
|
47c84fc289 | ||
|
|
2e273dc630 | ||
|
|
68c5ea82e7 | ||
|
|
c1ea4d470b | ||
|
|
7f688d2ed0 | ||
|
|
42bc31e406 | ||
|
|
19569aefa4 | ||
|
|
e9a11013a4 | ||
|
|
59fa8403de | ||
|
|
1c18dc3661 | ||
|
|
81c7d24867 | ||
|
|
bd41801c8d | ||
|
|
c4a9545d28 | ||
|
|
34deacb881 | ||
|
|
6dc48b6732 | ||
|
|
4d7c1020b0 | ||
|
|
909f6ab08b | ||
|
|
464baabf96 | ||
|
|
aaafce4ace | ||
|
|
dd20054151 | ||
|
|
dbedc4bc08 | ||
|
|
3aefcb062f | ||
|
|
c5ad1953ad | ||
|
|
f52821d1cd | ||
|
|
f49c633e77 | ||
|
|
23187859d6 | ||
|
|
bf33f4f52e | ||
|
|
a845b7ac52 | ||
|
|
c8e52e7bde | ||
|
|
8550df69eb | ||
|
|
eefb4be44b | ||
|
|
b8e96989af | ||
|
|
e814309750 | ||
|
|
d42d9d3743 | ||
|
|
10beffe167 | ||
|
|
c2e08540d0 | ||
|
|
62f17a20af | ||
|
|
8374e4e3cd | ||
|
|
5aaea1f213 | ||
|
|
35f9609865 | ||
|
|
710bf8b636 | ||
|
|
211180a801 | ||
|
|
bb6ce06e5a | ||
|
|
6363f15cb9 | ||
|
|
838a43428b | ||
|
|
5cf14eb15b | ||
|
|
adc92fbdb0 | ||
|
|
dbe56638f9 | ||
|
|
cd7c850a16 | ||
|
|
3d1ca99027 | ||
|
|
89f966bb68 | ||
|
|
42e2e0284b | ||
|
|
c2c7edf1b7 | ||
|
|
09d79d775f | ||
|
|
c6bc81b0df | ||
|
|
8acb54985c | ||
|
|
ec2bc6504b | ||
|
|
154ebe294a | ||
|
|
61f2b01172 | ||
|
|
a0c42225a4 | ||
|
|
a959ff25a4 | ||
|
|
0b0e2fd377 | ||
|
|
b6bc118297 | ||
|
|
635b10a3dc | ||
|
|
79ef9aaeb0 | ||
|
|
b31983e30b | ||
|
|
8430dda888 | ||
|
|
87bdbd520f | ||
|
|
e32367dc0b | ||
|
|
e37bf31cd3 | ||
|
|
b781731ecc | ||
|
|
9ec817c1c6 | ||
|
|
e2185e9269 | ||
|
|
381d1d8573 | ||
|
|
ae707f7768 | ||
|
|
484cffc136 | ||
|
|
7060bf2c16 | ||
|
|
f86ebb6e66 | ||
|
|
3868efcead | ||
|
|
49ddc9ebd1 | ||
|
|
60a4b103ab | ||
|
|
bd9c4a5fea | ||
|
|
7cf9cf8d3e | ||
|
|
6d9a32d28b | ||
|
|
513d964a8b | ||
|
|
c6867de13d | ||
|
|
b0fb43d678 | ||
|
|
4a2c164188 | ||
|
|
308cca9b7d | ||
|
|
4c6aed3cff | ||
|
|
e6554e09c7 | ||
|
|
5d1e98dafd | ||
|
|
ca3dbab49d | ||
|
|
d250394580 | ||
|
|
6eaf48aefe | ||
|
|
1c804b05b7 | ||
|
|
2fcf3f10c7 | ||
|
|
babc210a38 | ||
|
|
cfea463c7b | ||
|
|
0a23af61f9 | ||
|
|
f14bfc3222 | ||
|
|
943619a657 | ||
|
|
cd04995b65 | ||
|
|
b584991f5c | ||
|
|
b5c372f109 | ||
|
|
01cf789f5d | ||
|
|
024d7b427a | ||
|
|
1b87497e15 | ||
|
|
d7d1859aa0 | ||
|
|
1311df5759 | ||
|
|
03ea6accc1 | ||
|
|
f8aafe9265 | ||
|
|
37d74ca2a6 | ||
|
|
46c6153201 | ||
|
|
46fd7fcad4 | ||
|
|
e251bf0072 | ||
|
|
2503e567f5 | ||
|
|
88855251e9 | ||
|
|
a98b4c84ff | ||
|
|
d2a4e9a4a1 | ||
|
|
ff9080a766 | ||
|
|
3abcba5991 | ||
|
|
2e1710d3a9 | ||
|
|
928e03ce02 | ||
|
|
88aeb357cd | ||
|
|
8908079022 | ||
|
|
495831da29 | ||
|
|
7ada2e8975 | ||
|
|
3c51d3b1ea | ||
|
|
119c81c770 | ||
|
|
06dcf70514 | ||
|
|
4d6b9b52e3 | ||
|
|
49a0b27d29 | ||
|
|
e5701a8dae | ||
|
|
a4894aae9d | ||
|
|
c1826aea98 | ||
|
|
95422e6d21 | ||
|
|
1ed46dff9c | ||
|
|
9b654b1ad8 | ||
|
|
e7c21fb907 | ||
|
|
2cf7c66187 | ||
|
|
cc8888fc69 | ||
|
|
b9d7033724 | ||
|
|
75cdfbad8d | ||
|
|
3707fc35fc | ||
|
|
0f7c8be060 | ||
|
|
13c75b9e35 | ||
|
|
4a49a198f0 | ||
|
|
53a4fce934 | ||
|
|
ed2057e4a2 | ||
|
|
8738c74d7f | ||
|
|
c9db2fb29e | ||
|
|
41e3f50dbe | ||
|
|
5df375d490 | ||
|
|
0312a3b099 | ||
|
|
a174c355d2 | ||
|
|
8a3aa56c11 | ||
|
|
c13b1fa78f | ||
|
|
31e132d4fd | ||
|
|
37e79d9c41 | ||
|
|
87d4f5c64e | ||
|
|
b989815829 | ||
|
|
814a4a201a | ||
|
|
5589609b1b | ||
|
|
5238a0fbb3 | ||
|
|
78f1e8a993 | ||
|
|
666dd48412 | ||
|
|
eb1e2e2a5e |
No files matched your search
@@ -1,5 +1,5 @@
|
||||
name: Install dependencies
|
||||
description: Set up pnpm and Node.js, restore caches and run pnpm install
|
||||
description: Set up pnpm and Node.js and run pnpm install
|
||||
|
||||
inputs:
|
||||
node-version:
|
||||
@@ -12,40 +12,15 @@ inputs:
|
||||
runs:
|
||||
using: composite
|
||||
steps:
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v7
|
||||
with:
|
||||
node-version: ${{ inputs.node-version }}
|
||||
package-manager-cache: false
|
||||
|
||||
# The lockfile is not committed, so the usual lockfile hash key does not
|
||||
# apply. Instead a new store snapshot is saved whenever a package.json
|
||||
# changes or a week passes, and every run restores the most recent one.
|
||||
- id: store
|
||||
shell: bash
|
||||
run: |
|
||||
echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
|
||||
echo "week=$(date -u +%G-%V)" >> "$GITHUB_OUTPUT"
|
||||
- uses: actions/cache@v6
|
||||
with:
|
||||
path: ${{ steps.store.outputs.path }}
|
||||
key: pnpm-store-${{ runner.os }}-${{ steps.store.outputs.week }}-${{ hashFiles('**/package.json', 'pnpm-workspace.yaml') }}
|
||||
restore-keys: pnpm-store-${{ runner.os }}-
|
||||
|
||||
# The prepare scripts run tsc --build, which is incremental when its
|
||||
# previous output is present. Every run saves its output and the next run
|
||||
# starts from the most recent one.
|
||||
- if: inputs.ignore-scripts != 'true'
|
||||
uses: actions/cache@v6
|
||||
with:
|
||||
path: |
|
||||
packages/*/dist
|
||||
plugins/*/dist
|
||||
key: build-${{ runner.os }}-${{ github.sha }}
|
||||
restore-keys: build-${{ runner.os }}-
|
||||
# pnpm/action-setup installs a bootstrap pnpm and then switches to the
|
||||
# packageManager version, which takes about 10 seconds.
|
||||
- shell: bash
|
||||
run: npm install --global --no-audit --no-fund "$(node -p 'require("./package.json").packageManager.split("+")[0]')"
|
||||
|
||||
- shell: bash
|
||||
run: pnpm i --no-frozen-lockfile ${{ inputs.ignore-scripts == 'true' && '--ignore-scripts' || '' }}
|
||||
# Drop packages the restored store had but this install did not use, so
|
||||
# the snapshot does not grow with every version bump.
|
||||
- shell: bash
|
||||
run: pnpm store prune
|
||||
@@ -0,0 +1,30 @@
|
||||
name: Changelog
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, edited, synchronize, reopened]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
check:
|
||||
# Bot pull requests do not fill in the template.
|
||||
if: github.event.pull_request.user.type != 'Bot'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
sparse-checkout: scripts
|
||||
- uses: actions/setup-node@v7
|
||||
with:
|
||||
node-version: 24.x
|
||||
- name: Check changelog in pull request description
|
||||
env:
|
||||
PR_BODY: ${{ github.event.pull_request.body }}
|
||||
run: node scripts/check_pr_changelog.mts
|
||||
@@ -4,6 +4,10 @@ on:
|
||||
push:
|
||||
pull_request:
|
||||
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref == 'refs/heads/master' && github.sha || github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
EMMYLUA_CHECK_VERSION: "0.25.1"
|
||||
|
||||
|
||||
@@ -7,6 +7,12 @@ on:
|
||||
push:
|
||||
pull_request:
|
||||
|
||||
# Superseded runs of a branch or pull request are cancelled. Runs on master
|
||||
# each get their own group so every commit there is tested.
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref == 'refs/heads/master' && github.sha || github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
env:
|
||||
NODE_VERSION: 24.x
|
||||
|
||||
@@ -22,17 +28,27 @@ jobs:
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
# Test Node.js 24 and 26 across the Factorio matrix; Node.js 22 runs coverage below.
|
||||
# To stay within the concurrent job limit, every Factorio version is
|
||||
# tested on the latest Node.js, and the oldest supported Node.js only
|
||||
# with the latest Factorio. Versions in between are not tested.
|
||||
# Coverage is performed on the oldest supported Node.js.
|
||||
# Node.js release schedule: https://nodejs.org/en/about/releases/
|
||||
node-version: [24.x, 26.x]
|
||||
|
||||
# Supported factorio versions are latest stable and one minor version before stable (even if from a previous major)
|
||||
# Supported factorio versions are latest stable and one minor version before stable (even if from a previous major)
|
||||
node-version: [26.x]
|
||||
factorio-version: [1.1.110, 2.0.77, 2.1.17]
|
||||
|
||||
# Coverage is performed on the older of the supported node versions
|
||||
|
||||
# The tests run in two halves of similar length on separate runners,
|
||||
# the clusterioctl, plugin system and instance integration tests and the rest.
|
||||
tests: [ctl, other]
|
||||
|
||||
include:
|
||||
- node-version: 22.x
|
||||
factorio-version: 2.1.17
|
||||
tests: ctl
|
||||
coverage: true
|
||||
- node-version: 22.x
|
||||
factorio-version: 2.1.17
|
||||
tests: other
|
||||
coverage: true
|
||||
|
||||
steps:
|
||||
@@ -45,21 +61,29 @@ jobs:
|
||||
run: wget -q -O factorio.tar.gz https://www.factorio.com/get-download/${{ matrix.factorio-version }}/headless/linux64 && tar -xf factorio.tar.gz && rm factorio.tar.gz
|
||||
- name: Run tests
|
||||
if: ${{ !matrix.coverage }}
|
||||
run: pnpm test
|
||||
env:
|
||||
# Re-run with debug logging to see output from passing tests
|
||||
TEST_OUTPUT: ${{ runner.debug == '1' && 'verbose' || 'normal' }}
|
||||
run: pnpm test --grep "^(Integration of Clusterio (clusterioctl|plugin system)|Clusterio Instance) " ${{ matrix.tests == 'other' && '--invert' || '' }}
|
||||
- name: Run coverage
|
||||
if: ${{ matrix.coverage }}
|
||||
run: pnpm run ci-cover
|
||||
env:
|
||||
# Re-run with debug logging to see output from passing tests
|
||||
TEST_OUTPUT: ${{ runner.debug == '1' && 'verbose' || 'normal' }}
|
||||
run: pnpm run ci-cover --grep "^(Integration of Clusterio (clusterioctl|plugin system)|Clusterio Instance) " ${{ matrix.tests == 'other' && '--invert' || '' }}
|
||||
- name: Upload coverage to Codecov
|
||||
if: ${{ matrix.coverage }}
|
||||
uses: codecov/codecov-action@v7
|
||||
with:
|
||||
files: ./coverage/lcov.info
|
||||
# Otherwise the raw V8 coverage in coverage/tmp is uploaded as well
|
||||
disable_search: true
|
||||
token: ${{ secrets.CODECOV_TOKEN }}
|
||||
- name: Upload test logs for debugging
|
||||
if: ${{ !cancelled() }}
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: logs-${{ matrix.node-version }}-${{ matrix.factorio-version }}
|
||||
name: logs-${{ matrix.node-version }}-${{ matrix.factorio-version }}-${{ matrix.tests }}
|
||||
path: temp/test/logs
|
||||
|
||||
version-compat:
|
||||
@@ -87,8 +111,6 @@ jobs:
|
||||
uses: ./.github/actions/pnpm-install
|
||||
with:
|
||||
node-version: ${{ env.NODE_VERSION }}
|
||||
- name: Build
|
||||
run: pnpm run build
|
||||
- name: Test ${{ matrix.controller }} controller with ${{ matrix.host }} host
|
||||
run: >
|
||||
node scripts/version-compat-test.js
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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).
|
||||
+274
-35
@@ -1,35 +1,220 @@
|
||||
# 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
|
||||
|
||||
|
||||
## Version 2.1.1
|
||||
|
||||
### Features
|
||||
|
||||
- Hosts on ARM64 Linux download and run the ARM64 headless build of Factorio, available from Factorio 2.1.18. [#1228](<https://github.com/clusterio/clusterio/pull/1228>)
|
||||
- Added `requiredMods` to plugin declarations. Instances refuse to start when their mod pack lacks a mod a loaded plugin requires, and the controller downloads missing required mods and their dependencies from the mod portal on start. Subspace Storage requires the subspace_storage mod. [#535](<https://github.com/clusterio/clusterio/issues/535>)
|
||||
- Added `--output json` and `--output wire` to clusterioctl for machine readable results and errors. [#1230](<https://github.com/clusterio/clusterio/pull/1230>)
|
||||
|
||||
### Fixes
|
||||
|
||||
- Fixed a newly paired host reporting that it needs a restart. [#1204](<https://github.com/clusterio/clusterio/issues/1204>)
|
||||
- Fixed the installer's run-controller and run-host scripts exiting with 0 when the controller or host exited with 8 to stop the restart loop. [#1208](<https://github.com/clusterio/clusterio/issues/1208>)
|
||||
- Fixed clusterioctl user list, user show and role list printing [object Set] for roles, instances and permissions. [#1205](<https://github.com/clusterio/clusterio/issues/1205>)
|
||||
- Fixed typo in the delete instance confirmation. [#1209](<https://github.com/clusterio/clusterio/issues/1209>)
|
||||
- The Search Mod Portal dialog now opens on the default mod pack's Factorio version instead of always 2.0. [#1209](<https://github.com/clusterio/clusterio/issues/1209>)
|
||||
- Fixed the mod portal cache key logging "undefined" when hide_deprecated was not sent. [#1209](<https://github.com/clusterio/clusterio/issues/1209>)
|
||||
- Fixed player_sync losing quick bar slots of blueprint library records when a player joins an instance for the first time. [#1219](<https://github.com/clusterio/clusterio/issues/1219>)
|
||||
- Fixed cramped plugin rows and wrapping header branding on mobile screens. [#1223](<https://github.com/clusterio/clusterio/pull/1223>)
|
||||
- Fixed player_sync keeping an instance's old copy of a player after the controller refused its upload, which let an instance restarted after a crash overwrite newer player data. [#1218](<https://github.com/clusterio/clusterio/issues/1218>)
|
||||
|
||||
### Changes
|
||||
|
||||
- Restarting the controller or a host from the web interface now asks for confirmation, and for hosts lists the running instances that will be stopped. [#1207](<https://github.com/clusterio/clusterio/issues/1207>)
|
||||
- New clusters default controller.default_mod_pack_id to the newest Base Game mod pack, so instances can create saves and start without setting it first. [#1203](<https://github.com/clusterio/clusterio/issues/1203>)
|
||||
- Output from npm during `plugin install` now goes through the logger. [#1224](<https://github.com/clusterio/clusterio/pull/1224>)
|
||||
- The controller collects system info, including restart required, right after it starts and when a host connects instead of waiting for the first system metrics interval. [#1227](<https://github.com/clusterio/clusterio/pull/1227>)
|
||||
- clusterioctl prints all tables with the same formatter and prints command results to stdout instead of the log. [#1230](<https://github.com/clusterio/clusterio/pull/1230>)
|
||||
- clusterioctl prints "Command ran successfully" for commands that have no other output. [#1230](<https://github.com/clusterio/clusterio/pull/1230>)
|
||||
|
||||
### Meta
|
||||
|
||||
- Added a CI check that pull request descriptions have a valid changelog section. [#1226](<https://github.com/clusterio/clusterio/pull/1226>)
|
||||
|
||||
### Contributors
|
||||
|
||||
Many thanks to the following for contributing to this release:
|
||||
[@bbassie](<https://github.com/bbassie>), [@ILLISIS](<https://github.com/ILLISIS>), [@Danielv123](<https://github.com/Danielv123>)
|
||||
|
||||
### Statistics
|
||||
|
||||
Commits: 44 Pull Requests: 19 Files Changed: 81 Additions: +2,676 Deletions: -739
|
||||
|
||||
|
||||
## Version 2.1.0
|
||||
|
||||
### Features
|
||||
|
||||
- Added `Instance.autoPaused` and the `autoPauseChanged` instance hook so plugins can skip periodic commands while the game is auto paused. [#258](<https://github.com/clusterio/clusterio/issues/258>)
|
||||
- Hosts ask to join the cluster when first started and are approved in the web interface or with clusterioctl host approve. [#1161](<https://github.com/clusterio/clusterio/pull/1161>)
|
||||
- Exporting data from an instance running the headless build of Factorio now reads the base game's icons from a full install of the same version in `host.factorio_directory`, if there is one. [#1068](<https://github.com/clusterio/clusterio/issues/1068>)
|
||||
- Added instance templates that other instances inherit config values from, with linked inherited values in the web interface, see `instance.is_template` and `instance.template_id`. [#200](<https://github.com/clusterio/clusterio/issues/200>)
|
||||
- Added the mod pack an instance uses to the instance list and instance page, with a link to it. [#852](<https://github.com/clusterio/clusterio/issues/852>)
|
||||
- Added controller metrics for WebSocket ready, resume, drop, session timeout and failed resume events. [#1192](<https://github.com/clusterio/clusterio/issues/1192>)
|
||||
- Added online player count column to the instance list in the web interface. [#1193](<https://github.com/clusterio/clusterio/issues/1193>)
|
||||
- Added controller.log_retention_days and host.log_retention_days to delete log files older than the given number of days. [#1200](<https://github.com/clusterio/clusterio/pull/1200>)
|
||||
- Added a plugin browser to the plugins page that searches npm for packages with the clusterio-plugin keyword and installs them on a chosen set of machines, defaulting to every connected machine that allows remote installs. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added a field to the plugin browser for installing a package by name. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added a Versions column to the plugins page showing how many machines run each plugin version now and after a restart, with restart pending, disabled, not installed and offline counts. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added a table of machines to the plugin page with the version and status of the plugin on each, and an install or update button for machines that aren't on the latest version. Plugins only installed on hosts have a page too. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added "Update to X" and "Update all" actions to the plugins page that bring every machine to the latest version of a plugin on npm, installing it where it's missing, with a checklist of the changes to make. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added a "Restart pending" action to the plugins page that restarts the chosen machines with a pending restart, hosts first and the controller last. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added support for `name@version` in plugin install and update requests and the matching clusterioctl commands, for installing a specific version or updating past the range saved in package.json. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added `PluginLatestVersionsRequest` for looking up the latest version of plugins published on npm. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added `controller plugin search` command to clusterioctl. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added `core.plugin.search` permission. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Added a `handleSignals` constructor argument to `LockFile` for locks that should only be released on exit. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
|
||||
### Fixes
|
||||
|
||||
- Fixed the plugin template asking for an older TypeBox version than lib, which made new plugins fail to compile. [#1127](<https://github.com/clusterio/clusterio/issues/1127>)
|
||||
- Fixed subspace_storage and statistics_exporter keeping auto paused servers running with their periodic RCON commands. [#258](<https://github.com/clusterio/clusterio/issues/258>)
|
||||
- Fixed research_sync losing research progress and finished research while the controller was unreachable. [#1123](<https://github.com/clusterio/clusterio/issues/1123>)
|
||||
- Fixed stopping an instance while it is starting failing with "Expected state running but state is stopping" or leaving it running. The stop now takes effect once the instance has started, and the control button shows as loading while the instance is starting or stopping. [#879](<https://github.com/clusterio/clusterio/issues/879>)
|
||||
- Raised the required Node.js version to 22.18 or 24.2, since earlier 22.x and 24.x releases silently skipped CLI startup. [#1109](<https://github.com/clusterio/clusterio/issues/1109>)
|
||||
- Fixed user view page not updating the displayed roles when they change. [#775](<https://github.com/clusterio/clusterio/issues/775>)
|
||||
- Fixed role view page discarding unsaved edits when the role is updated, and not showing changes made elsewhere alongside local edits. [#776](<https://github.com/clusterio/clusterio/issues/776>)
|
||||
- Fixed data export failing completely when one icon could not be read or decoded, the icon is now skipped with a warning. [#841](<https://github.com/clusterio/clusterio/issues/841>)
|
||||
- Fixed mod settings added by a data export showing up empty on an open mod pack page until it was reloaded. [#840](<https://github.com/clusterio/clusterio/issues/840>)
|
||||
- Fixed Player Sync dropping recipe notifications on download when the player had no cleared recipes, which also replaced the stored list on the next upload. [#964](<https://github.com/clusterio/clusterio/issues/964>)
|
||||
- Fixed export-data on headless Factorio counting blank layered icons as exported and not reporting that the base game icons were missing. [#1068](<https://github.com/clusterio/clusterio/issues/1068>)
|
||||
- Controller drops export data whose files were deleted, at startup or when a missing file is requested, and the web interface falls back cleanly instead of showing errors. [#878](<https://github.com/clusterio/clusterio/issues/878>)
|
||||
- Fixed player_sync leaving a player as a spectator with no body, and uploading that empty state, after a download stalled while the controller was down. [#1124](<https://github.com/clusterio/clusterio/issues/1124>)
|
||||
- Fixed player_sync teleporting a player back after another mod, such as universal edges, teleported them while their player data downloaded. [#908](<https://github.com/clusterio/clusterio/issues/908>)
|
||||
- Fixed plugins that need save patching, script commands or Lua UDP defaulting to loaded on instances with that feature disabled, which made saving the instance config fail. [#651](<https://github.com/clusterio/clusterio/issues/651>)
|
||||
- Fixed Player Sync keeping cleared recipe notifications and losing ones for recipes missing here when a download changed the player's force. [#964](<https://github.com/clusterio/clusterio/issues/964>)
|
||||
- Fixed the instance filter on the users page and the icon reference search being lost when navigating back to the page. [#1185](<https://github.com/clusterio/clusterio/pull/1185>)
|
||||
- Fixed the web UI ignoring `localised_name` and `localised_description` of mod settings and showing rich text tags in setting names. [#768](<https://github.com/clusterio/clusterio/issues/768>)
|
||||
- Fixed saves patched by a newer version of Clusterio not being rejected. [#1184](<https://github.com/clusterio/clusterio/pull/1184>)
|
||||
- Fixed the research_sync queue chat line showing the same level for every queued level of an infinite technology. [#1186](<https://github.com/clusterio/clusterio/issues/1186>)
|
||||
- Fixed the web interface logging MaxListenersExceededWarning when plugins create more than 7 subscribers. [#1145](<https://github.com/clusterio/clusterio/issues/1145>)
|
||||
- Fixed Player Sync failing with "Failed to create character" when the player was in a chunk that was not generated yet or had no land nearby. [#1187](<https://github.com/clusterio/clusterio/issues/1187>)
|
||||
- Fixed player_sync not syncing which page each quick bar row shows, so the quick bar could show other slots after switching servers. [#1201](<https://github.com/clusterio/clusterio/issues/1201>)
|
||||
- Fixed the controller reading the whole body of save, mod and export uploads it had rejected, when running behind a reverse proxy. [#595](<https://github.com/clusterio/clusterio/issues/595>)
|
||||
- Fixed uploads to the controller taking more than 5 minutes failing. [#1173](<https://github.com/clusterio/clusterio/pull/1173>)
|
||||
- Fixed a plugin list entry for a path that no longer exists taking precedence over an npm package providing the same plugin. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Fixed npm plugins already in the plugin list logging "already in the plugin list, but with a different path" on every startup. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
|
||||
### Changes
|
||||
|
||||
- Errors thrown by request handlers are received by the requester as the same class instead of a generic `RequestError`. Plugins can register their own error classes with `errors` in the plugin declaration. [#900](<https://github.com/clusterio/clusterio/issues/900>)
|
||||
- Replaced webpack with Vite for building the web interface and plugin web modules. `--dev` now uses the Vite development server with hot module replacement. [#1127](<https://github.com/clusterio/clusterio/issues/1127>)
|
||||
- Removed the separate web interface load state from the plugins pages, web load errors now show with the plugin's versions. [#1140](<https://github.com/clusterio/clusterio/pull/1140>)
|
||||
- Build the published packages with TypeScript 7, and use it in the plugin template. Plugins can keep using TypeScript 5.9 or 6. [#1147](<https://github.com/clusterio/clusterio/pull/1147>)
|
||||
- `ctl host plugin list` shows the plugin state in place of the loaded and enabled columns. [#1134](<https://github.com/clusterio/clusterio/issues/1134>)
|
||||
- Reduced the size of a host install by replacing jimp with only the jimp modules the export uses. [#1162](<https://github.com/clusterio/clusterio/pull/1162>)
|
||||
- `@clusterio/web_ui` no longer installs typescript. Plugins that compile with `tsc` need typescript in their own devDependencies. [#1163](<https://github.com/clusterio/clusterio/pull/1163>)
|
||||
- Commands of clusteriocontroller and clusteriohost that don't start the server, like config and bootstrap, start about 45% faster. [#1159](<https://github.com/clusterio/clusterio/pull/1159>)
|
||||
- Made web interface view pages show resources that are loading, missing, deleted or failed to load the same way, instead of spinning forever without the subscribe permission. [#1165](<https://github.com/clusterio/clusterio/issues/1165>)
|
||||
- Added `ResourceState` and `useResourceState` to the web_ui package, and `useHost`, `useInstance`, `useUser`, `useRole` and `useModPack` now also return the subscription error. [#1165](<https://github.com/clusterio/clusterio/issues/1165>)
|
||||
- Reduced the download size of the create tool by replacing inquirer 8 with the standalone @inquirer prompt packages. [#1164](<https://github.com/clusterio/clusterio/pull/1164>)
|
||||
- `clusterioctl instance config edit` only sends the fields changed in the editor. [#200](<https://github.com/clusterio/clusterio/issues/200>)
|
||||
- Mod settings that no mod in a mod pack's export data defines are now hidden in a collapsed section on the mod pack page and can be removed from there. [#773](<https://github.com/clusterio/clusterio/issues/773>)
|
||||
- Added `UserManager.verifyUserToken` for checking user tokens. [#1180](<https://github.com/clusterio/clusterio/pull/1180>)
|
||||
- subspace_storage now requires save patching on the instance, it did not work without it. [#651](<https://github.com/clusterio/clusterio/issues/651>)
|
||||
- Saves started with save patching disabled now have the Clusterio modules removed and their original control.lua restored. [#651](<https://github.com/clusterio/clusterio/issues/651>)
|
||||
- The research_sync chat line for a research queue change names only the technologies added, removed or moved, instead of printing the whole queue. [#1186](<https://github.com/clusterio/clusterio/issues/1186>)
|
||||
- Focused the search input when opening mod search on the mods page and the mod pack view. [#1194](<https://github.com/clusterio/clusterio/issues/1194>)
|
||||
- The online player list on the instance page is always shown, collapsed when no players are online. [#1191](<https://github.com/clusterio/clusterio/issues/1191>)
|
||||
- The installer detects Factorio installed through Steam on macOS. [#1190](<https://github.com/clusterio/clusterio/issues/1190>)
|
||||
- Log files older than 30 days are now deleted by default. Existing installs will lose logs older than 30 days on the first start after upgrading. To keep them, set controller.log_retention_days and host.log_retention_days to 0 with the config command after upgrading but before starting the controller and hosts. [#1200](<https://github.com/clusterio/clusterio/pull/1200>)
|
||||
- Requests to the controller moving less than controller.transfer_min_progress KiB in 30 seconds are now closed. [#842](<https://github.com/clusterio/clusterio/issues/842>)
|
||||
- Plugin lists now include the version installed on disk and npm plugins installed since startup. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- System metrics now include the plugins on each machine, kept for hosts while they are offline. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- The "Updates" button on the host and controller pages is now "Update Clusterio" and no longer installs or updates plugins. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Plugin installs and updates are rejected while another npm operation is running on the same machine, including between a standalone controller and host sharing an installation directory. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Plugin installs and pinned updates are rejected when the package by that name is installed from a path, git, url, tarball or alias, either by the root package.json or by another plugin, as installing by name would replace it. Such plugins no longer report an npm package. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Hosts and the controller refuse to restart while a plugin install or update is running on the machine. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Lock files now include the process start time, so a lock left by an earlier process with the same pid is treated as stale. A lock file is only removed by the process that wrote it. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
- Plugins in `optionalDependencies` are now found on startup, and their entries override `dependencies` of the same name like they do in npm. [#1001](<https://github.com/clusterio/clusterio/issues/1001>)
|
||||
|
||||
### Breaking Changes
|
||||
|
||||
- Removed `lib.findUnusedName`, its result could be taken by another process before use. [#1128](<https://github.com/clusterio/clusterio/pull/1128>)
|
||||
- Replaced `DatastoreProvider.bootstrap()` with `KeyValueDatastore.fromProvider()` and `SubscribableDatastore.fromProvider()`, and `Controller.bootstrap()` / `Host.bootstrap()` with `Controller.fromConfig()` / `Host.fromConfig()`. [#1126](<https://github.com/clusterio/clusterio/issues/1126>)
|
||||
- Replaced `FactorioServer.init()` and `setTargetVersion()` with `FactorioServer.fromOptions()`, and `FactorioServer.checkForUpdates()` with an exported `checkForUpdates()` function. [#1126](<https://github.com/clusterio/clusterio/issues/1126>)
|
||||
- Replaced `Instance.init()` with `Instance.fromConfig()` followed by `instance.loadPlugins()`. The `Instance` constructor now takes the `FactorioServer` instead of the factorio directory. [#1126](<https://github.com/clusterio/clusterio/issues/1126>)
|
||||
- Replaced `RequestError` with error classes following HTTP status codes: `ClientError` (`ValidationError`, `ForbiddenError`, `NotFoundError`, `TimeoutError`, `ConflictError`) and `ServerError` (`InternalServerError`, `UnavailableError`). [#900](<https://github.com/clusterio/clusterio/issues/900>)
|
||||
- Renamed `InvalidValue`, `InvalidField` and `InvalidAccess` to `InvalidValueError`, `InvalidFieldError` and `InvalidAccessError`. [#900](<https://github.com/clusterio/clusterio/issues/900>)
|
||||
- Plugin web modules must be built with Vite using `clusterioPlugin` from `@clusterio/web_ui/vite.mjs`. Plugins built with webpack no longer load. See docs/devs/plugin-migration-to-2.1.md. [#1127](<https://github.com/clusterio/clusterio/issues/1127>)
|
||||
- Renamed `lib.PluginWebpackEnvInfo` to `lib.PluginWebEnvInfo`. [#1127](<https://github.com/clusterio/clusterio/issues/1127>)
|
||||
- `PluginDetails` takes a `state` in place of `loaded` and `enabled`, use the `loaded` and `loadsOnRestart` getters to read them. [#1134](<https://github.com/clusterio/clusterio/issues/1134>)
|
||||
- Node.js 22.0 to 22.17 and 24.0 to 24.1 are no longer supported. [#1109](<https://github.com/clusterio/clusterio/issues/1109>)
|
||||
- Removed host token management: clusterioctl host generate-token, revoke-token and create-config, bootstrap generate-host-token and their permissions. Hosts are revoked from the host page or with clusterioctl host revoke. [#1161](<https://github.com/clusterio/clusterio/pull/1161>)
|
||||
- Renamed `lib.safeOutputFile` to `lib.atomicOverwriteFile`. [#876](<https://github.com/clusterio/clusterio/issues/876>)
|
||||
- Added `HostManager` as `controller.hosts`; the hosts datastore moved to `controller.hosts.records`, `Controller.generateHostToken` and `verifyHostToken` became `controller.hosts.signHostToken` and `verifyHostToken`, and `HostPairingManager.createHost` became `controller.hosts.createHost`, which returns the host record. [#1180](<https://github.com/clusterio/clusterio/pull/1180>)
|
||||
|
||||
### Meta
|
||||
|
||||
- Replaced ESLint with Oxlint. [#1127](<https://github.com/clusterio/clusterio/issues/1127>)
|
||||
- Removed TypeDoc and the `pnpm docs` script. [#1147](<https://github.com/clusterio/clusterio/pull/1147>)
|
||||
|
||||
### Contributors
|
||||
|
||||
Many thanks to the following for contributing to this release:
|
||||
[@psihius](<https://github.com/psihius>), [@bbassie](<https://github.com/bbassie>), [@Danielv123](<https://github.com/Danielv123>), [@ILLISIS](<https://github.com/ILLISIS>)
|
||||
|
||||
### Statistics
|
||||
|
||||
Commits: 148 Pull Requests: 55 Files Changed: 296 Additions: +17,343 Deletions: -4,190
|
||||
|
||||
Many thanks to the following for contributing to this release:
|
||||
[@username](https://github.com/username)
|
||||
-->
|
||||
|
||||
## Version 2.0.3
|
||||
|
||||
@@ -809,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
|
||||
|
||||
@@ -826,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
|
||||
|
||||
@@ -844,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.
|
||||
@@ -887,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
|
||||
|
||||
@@ -895,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.
|
||||
@@ -950,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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -87,10 +87,12 @@ Install dependencies with:
|
||||
|
||||
This installs dependencies and builds the packages.
|
||||
`pnpm-lock.yaml` is intentionally ignored; do not force-add it or assume a frozen-lockfile install is supported.
|
||||
For a fresh development cluster, run the installer and select standalone mode to create `config-controller.json`, `config-host.json`, and the credentials needed to connect them:
|
||||
For a fresh development cluster, run the installer and select standalone mode to create `config-controller.json` and `config-host.json`:
|
||||
|
||||
node packages/create --dev
|
||||
|
||||
The first time the host starts it prints a link for approving it in the web interface.
|
||||
|
||||
You can skip this step if you already have a working controller and host configuration.
|
||||
|
||||
To add plugins to use in the development environment use
|
||||
@@ -123,6 +125,7 @@ For web development on the controller there are also the following flags:
|
||||
`--dev` - Serve the `web_ui` package from source through Vite's development server with hot module replacement.
|
||||
|
||||
`--dev-plugin [name]` - Serve the web module for the given plugin from source the same way.
|
||||
This also serves the `web_ui` package from source, as the plugin has to share its modules with it.
|
||||
|
||||
These options can be combined and multiple plugins can be actived for dev mode.
|
||||
Keep in mind if you're working on external plugins the `--dev-plugin` option is likely to only work if the plugin is placed inside the `external_plugins` directory and its dependencies are installed with pnpm as part of the clusterio repository workspace.
|
||||
@@ -194,6 +197,9 @@ Use `pnpm run fast-test` to skip tests marked as slow, or `pnpm run no-external-
|
||||
These correspond to setting the `FAST_TEST` and `NO_EXTERNAL_TEST` environment variables and can be combined.
|
||||
For example, `FAST_TEST=y NO_EXTERNAL_TEST=y pnpm test` combines both exclusions.
|
||||
These flags still run the remaining integration setup and tests; neither produces an isolated unit-test run.
|
||||
Console and log output is only printed for tests and hooks that fail, just above the failure.
|
||||
Set `TEST_OUTPUT=verbose` to print all of it as it happens, or `TEST_OUTPUT=silent` (`pnpm run silent-test`) to print only the results.
|
||||
In CI, re-running a job with debug logging enabled gives verbose output.
|
||||
When writing slow tests call `slowTest(this)`, and for external API tests call `externalTest(this)`; both are exported from `test/common.js`.
|
||||
For tests that need a Factorio installation, call `requiresFactorio(this)` in the test or pass the suite to `requiresFactorio`, imported from `test/integration/index.js`.
|
||||
`test/common.js` also provides JSON round-trip/schema helpers, and `test/mock.js` provides shared mocks.
|
||||
@@ -217,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/`.
|
||||
@@ -254,8 +260,9 @@ 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.
|
||||
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).
|
||||
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/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.
|
||||
|
||||
@@ -325,34 +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 currently run on Node.js 24 and 26 across the Factorio matrix, with Node.js 22 used for coverage; see the [CI workflow](../.github/workflows/node.js.yml) for the version matrix.
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
+3
-1
@@ -11,7 +11,9 @@ RUN apt update \
|
||||
&& apt install -y wget \
|
||||
&& mkdir /clusterio
|
||||
WORKDIR /clusterio
|
||||
RUN wget -q -O factorio.tar.gz https://www.factorio.com/get-download/latest/headless/linux64 && tar -xf factorio.tar.gz && rm factorio.tar.gz
|
||||
ARG TARGETARCH
|
||||
RUN if [ "$TARGETARCH" = "arm64" ]; then build=linux-arm64; else build=linux64; fi \
|
||||
&& wget -q -O factorio.tar.gz https://www.factorio.com/get-download/latest/headless/$build && tar -xf factorio.tar.gz && rm factorio.tar.gz
|
||||
# Copy project files into the container
|
||||
COPY . .
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -129,6 +129,10 @@ Check out all our of decisions for [node, factorio, and operation support](/docs
|
||||
|
||||
3. Optionally copy the generated systemd service files in `systemd` folder to `/etc/systemd/system/`.
|
||||
|
||||
Hosts on Linux download the headless build of Factorio as needed.
|
||||
On ARM64 (aarch64) Linux this only works for Factorio 2.1.18 and later, which is the first version Factorio published an ARM64 headless build for.
|
||||
Older versions have to be installed manually, for example the x64 build run through an emulator.
|
||||
|
||||
|
||||
**Ubuntu with Docker**
|
||||
|
||||
@@ -219,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.
|
||||
|
||||

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

|
||||
|
||||
Once this is done, the mod settings will show up under the modpack configuration page.
|
||||
|
||||

|
||||
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
|
||||
@@ -251,8 +243,10 @@ Do not install the [Clusterio mod](https://mods.factorio.com/mod/clusterio), thi
|
||||
After completing the installation and creating your admin user, start up the controller and at least one host separately.
|
||||
The installer provides the `run-controller` and `run-host` scripts to make this simple.
|
||||
Once the controller process is running you can log into the web interface which is hosted by default on http://localhost:8080/ (adjust the port number if you changed it), use the admin authentication token provided from the installation to log in.
|
||||
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
|
||||
|
||||
@@ -272,26 +266,37 @@ If you have copied these files over to `/etc/systemd/system/` then you can start
|
||||
|
||||
## Setting up remote hosts
|
||||
|
||||
Run the installer as described in the installation section and choose "Host only" as the operating mode to install, it'll ask for a controller URL and an authentication token.
|
||||
The URL is the same as what is needed to connect to the web interface, and the authentication token can be generated on the Hosts page in the web interface.
|
||||
Once you start up the host it should show up in the Hosts list and be available for assigning and running instances on.
|
||||
Run the installer as described in the installation section and choose "Host only" as the operating mode to install, it'll ask for a name for the host and a controller URL.
|
||||
The URL is the same as what is needed to connect to the web interface.
|
||||
Then start the host, the first time it starts it prints a code and waits for the host to be approved:
|
||||
|
||||
Waiting for approval of "my-host" with code ABC-DEF, open this link to approve it:
|
||||
https://example.com/hosts?approve=ABC-DEF
|
||||
Or run: npx clusterioctl host approve ABC-DEF
|
||||
|
||||
Open the link to approve it in the web interface, where you can also change its name, or click Add host on the Hosts page and approve the request with the same code, or run `npx clusterioctl host approve <code>`.
|
||||
The host then saves its connection details and starts up, it should show up in the Hosts list and be available for assigning and running instances on.
|
||||
Only approve a request if its code matches the one shown by the host, approving gives the host full access to the cluster.
|
||||
Approving requires the `core.host.approve` permission, which the Cluster Admin role has.
|
||||
If you have that permission you can skip the wait by starting the host with `npx clusteriohost run --user-token <token>` and your own authentication token, it is only used to approve the host and is not saved.
|
||||
|
||||
To remove a host from the cluster, click Revoke host access on the page for the host in the web interface, or run `npx clusterioctl host revoke <host>`.
|
||||
This disconnects the host, its instances become unassigned and its saved connection details stop working.
|
||||
To add the computer back to the cluster start the host again, it asks for approval again.
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
- `@hornwitser/server_select@2.0.1` fails to load with Clusterio 2.0 because its entrypoints omit the required `.js` extension.
|
||||
`@hornwitser/discord_bridge@0.2.5` is not automatically discovered because it lacks the `clusterio-plugin` keyword.
|
||||
The Clusterio 2.0.2 installer still offers these versions; leave them unchecked until compatible plugin releases are available.
|
||||
The installer no longer offers them, but installs made with the 2.0.2 installer or earlier may still have them.
|
||||
If already installed, stop the controller and host, run `npm uninstall @hornwitser/server_select @hornwitser/discord_bridge` in each affected installation directory, and restart them to continue with the core plugins.
|
||||
See [#1102](https://github.com/clusterio/clusterio/issues/1102).
|
||||
- After updating Factorio you may get the error `Error: Expected empty response but got "Cannot execute command. Error: [string "clusterio_private.update_instance(..."]:1: attempt to index global 'clusterio_private' (a nil value)?` on instance start.
|
||||
|
||||
@@ -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.
|
||||
+120
-8
@@ -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.
|
||||
@@ -48,6 +48,33 @@ Must be greater than 0.
|
||||
Defaults to 60.
|
||||
|
||||
|
||||
### controller.log_retention_days
|
||||
|
||||
Number of days to keep the controller and cluster log files in the log directory for.
|
||||
Log files are named by the UTC date they were written and a file is deleted once its date is more than this many days in the past.
|
||||
Old files are checked for on startup and every hour after that.
|
||||
Set to 0 to keep logs forever.
|
||||
|
||||
Defaults to 30.
|
||||
|
||||
|
||||
### controller.host_pairing_timeout
|
||||
|
||||
Time in seconds a host can wait for approval before its request expires, after which the host requests again with a new code.
|
||||
Set to 0 for no limit.
|
||||
|
||||
Defaults to 3600.
|
||||
|
||||
|
||||
### controller.host_pairing_max_pending
|
||||
|
||||
Maximum number of hosts that can wait for approval at the same time.
|
||||
Hosts over the limit keep trying until there is room.
|
||||
Set to 0 for no limit.
|
||||
|
||||
Defaults to 50.
|
||||
|
||||
|
||||
### controller.http_port
|
||||
|
||||
Port to host HTTP server on.
|
||||
@@ -93,12 +120,20 @@ Defaults to null meaning the header is never trusted.
|
||||
### controller.public_url
|
||||
|
||||
Public address the controller is accessible on.
|
||||
Used as the URL in configs generated with `clusteriocontroller bootstrap create-ctl-config` and `clusterioctl host create-config`, and by plugins like Player Auth that need to show the address of the web interface in-game.
|
||||
Used as the URL in configs generated with `clusteriocontroller bootstrap create-ctl-config`, and by plugins like Player Auth that need to show the address of the web interface in-game.
|
||||
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.
|
||||
@@ -214,6 +249,22 @@ Must be greater than 0.
|
||||
Defaults to 15.
|
||||
|
||||
|
||||
### controller.transfer_min_speed
|
||||
|
||||
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.
|
||||
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 64.
|
||||
|
||||
|
||||
### controller.factorio_username
|
||||
|
||||
Username of the Factorio.com account to authenticate with the Factorio API with.
|
||||
@@ -244,6 +295,7 @@ Defaults to true.
|
||||
|
||||
ID of the mod pack to use for instances that don't have factorio.mod_pack_id set.
|
||||
Instances without a mod pack of their own fail to start if this is null.
|
||||
When the controller adds the default mod packs to a new cluster it sets this to the newest Base Game pack if it is null.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
@@ -277,7 +329,8 @@ 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.
|
||||
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
|
||||
The installer sets this, controller.allow_plugin_updates and controller.allow_plugin_install from one question about remote updates and plugin installs.
|
||||
See [Plugins (Remote)](/docs/clusterioctl.md#plugins-remote) for details on remote updates.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
@@ -326,6 +379,7 @@ Defaults to "New Host".
|
||||
### host.id
|
||||
|
||||
Immutable numeric id of the host which uniquely identifies this host in the cluster.
|
||||
The controller picks the id when the host is approved and the host writes it here, the controller does not accept hosts with an id it has not approved.
|
||||
Hidden in the web interface.
|
||||
|
||||
Defaults to a random 31 bit number.
|
||||
@@ -335,6 +389,7 @@ Defaults to a random 31 bit number.
|
||||
|
||||
Directory to look for the Factorio server(s) in.
|
||||
This can either point to a Factorio server directory, or to a directory containing multiple versions of the Factorio server.
|
||||
The headless build has no graphics, so when exporting data from an instance running it the base game's icons are read from a full install of the same major and minor version in this directory instead, if there is one.
|
||||
|
||||
Defaults to "factorio".
|
||||
|
||||
@@ -365,7 +420,9 @@ Defaults to "http://localhost:8080/".
|
||||
### host.controller_token
|
||||
|
||||
Access token used for authenticating with the controller.
|
||||
You can generate an access token with `clusterioctl host generate-token --id <host-id>`, or use the `clusterioctl host create-config` to create a new host config with the correct url and token in it.
|
||||
The host saves it together with host.id when it is approved, see [Setting up remote hosts](/README.md#setting-up-remote-hosts).
|
||||
The token only works while the host exists on the controller, if the host is revoked it asks to be approved again the next time it starts.
|
||||
Set it to `enter token here` to make the host ask to join again.
|
||||
The value can only be read and changed from the host itself.
|
||||
|
||||
Defaults to "enter token here".
|
||||
@@ -414,11 +471,21 @@ Must be greater than 0.
|
||||
Defaults to 60.
|
||||
|
||||
|
||||
### host.log_retention_days
|
||||
|
||||
Number of days to keep the host log files in the log directory for.
|
||||
Works the same way as controller.log_retention_days.
|
||||
Set to 0 to keep logs forever.
|
||||
|
||||
Defaults to 30.
|
||||
|
||||
|
||||
### host.allow_remote_updates
|
||||
|
||||
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.
|
||||
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
|
||||
The installer sets this, host.allow_plugin_updates and host.allow_plugin_install from one question about remote updates and plugin installs.
|
||||
See [Plugins (Remote)](/docs/clusterioctl.md#plugins-remote) for details on remote updates.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
@@ -490,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.
|
||||
@@ -498,6 +582,31 @@ This allows you to prevent certain instances from being started when using the b
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### instance.is_template
|
||||
|
||||
If enabled this instance is a template other instances can inherit config values from.
|
||||
Templates cannot be assigned to a host and therefore never start.
|
||||
Hidden from `instance list` in clusterioctl unless `--templates` is passed, and listed separately in the web interface.
|
||||
An instance cannot stop being a template while other instances inherit from it.
|
||||
Hidden in the web interface, set when creating the template.
|
||||
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### instance.template_id
|
||||
|
||||
ID of the template to inherit config values from.
|
||||
Inherited fields take their value from the template and follow it when it changes, setting a field on this instance stops inheriting it.
|
||||
Object fields like `factorio.settings` are inherited per property, properties set on this instance override the ones from the template.
|
||||
When set on an existing instance fields with the same value as the template or the default value become inherited, except the server name in `factorio.settings`.
|
||||
`instance.name`, `instance.is_template`, `instance.template_id`, the port fields, `factorio.rcon_password` and hidden fields are never inherited.
|
||||
A template may itself inherit from another template, but not from itself through a chain of templates.
|
||||
The fields currently inherited are stored in the hidden `instance.inherited_fields` field.
|
||||
In the web interface inherited values are linked and read only until they are unlinked.
|
||||
|
||||
Defaults to null meaning no template.
|
||||
|
||||
|
||||
### factorio.version
|
||||
|
||||
Version of Factorio to use for this instance.
|
||||
@@ -511,7 +620,8 @@ Defaults to "latest".
|
||||
### factorio.executable_path
|
||||
|
||||
Path relative to the Factorio installation directory of the executable to run.
|
||||
If null the path is auto detected, which is `bin/x64/factorio` on Linux and Windows and `MacOS/factorio` on macOS.
|
||||
If null the path is auto detected, which is `MacOS/factorio` on macOS and otherwise `bin/x64/factorio` or `bin/arm64/factorio`, whichever exists.
|
||||
When both exist the one matching the CPU is used.
|
||||
Only needed in special setups.
|
||||
|
||||
Defaults to null.
|
||||
@@ -591,6 +701,8 @@ Most plugins require the use of save patching to function.
|
||||
Turning it off makes it possible to use Clusterio to run and manage regular vanilla games and scenarios not compatible with Clusterio.
|
||||
Plugins that need save patching can't be loaded on the instance while this is disabled.
|
||||
Disabling it while such a plugin is loaded is rejected, and so is loading such a plugin while it is disabled.
|
||||
Saves patched before are restored to their original control.lua and have the modules removed when started with this disabled.
|
||||
Data the modules stored in the game is left in place.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
@@ -741,9 +853,9 @@ Defaults to 5.
|
||||
|
||||
Whether to load the given plugin on the instance.
|
||||
Note that plugins need to be loaded on the controller and the host in order for them to be loaded on instances.
|
||||
Loading a plugin that requires save patching or script commands is rejected while factorio.enable_save_patching or factorio.enable_script_commands respectively is disabled on the instance.
|
||||
Loading a plugin that requires save patching, script commands or Lua UDP is rejected while factorio.enable_save_patching, factorio.enable_script_commands or factorio.enable_lua_udp respectively is disabled on the instance.
|
||||
|
||||
Defaults to true.
|
||||
Defaults to true, or false if the instance does not have the features the plugin requires.
|
||||
|
||||
|
||||
## Ctl Configuration
|
||||
|
||||
@@ -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.
|
||||
@@ -45,6 +45,7 @@ For plugins the group name is the name of the plugin, e.g., the `level` field of
|
||||
**initialValue** (optional if optional is true):
|
||||
Value this config field should take in a newly initialized config.
|
||||
This can also be a synchronous function returning the value to use.
|
||||
The function is called with the config after its stored fields are loaded, so it can base the value on other fields.
|
||||
|
||||
**validator** (optional):
|
||||
Function called with the value being set and the config it belongs to.
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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`.
|
||||
@@ -59,3 +59,47 @@ Imports of `assert`, `buffer`, `events`, `os`, `path`, `process`, `stream`, `uti
|
||||
The `container` property of `WebPluginContext` is now the plugin's ES module namespace, `await container.get("./web")` returns the module instead of a factory function.
|
||||
|
||||
`lib.PluginWebpackEnvInfo` is renamed to `lib.PluginWebEnvInfo`.
|
||||
|
||||
|
||||
## Renamed lib functions
|
||||
|
||||
`lib.safeOutputFile` is renamed to `lib.atomicOverwriteFile`.
|
||||
It takes the same arguments.
|
||||
|
||||
|
||||
## Host pairing
|
||||
|
||||
Host tokens are no longer generated by users.
|
||||
A host joins the cluster by having the code it shows when it first starts approved, see [Host pairing](protocol.md#host-pairing) for the HTTP endpoints it uses.
|
||||
|
||||
- `HostGenerateTokenRequest` and `HostConfigCreateRequest` are removed.
|
||||
Pending requests are listed with `HostPairingListRequest`, approved with `HostPairingApproveRequest` and rejected with `HostPairingRejectRequest`, and changes to them are sent to subscribers of `HostPairingUpdatesEvent`.
|
||||
- `HostRevokeTokensRequest` is replaced by `HostRevokeRequest`, which deletes the host instead of only invalidating its tokens.
|
||||
Instances assigned to the host become unassigned.
|
||||
- The permissions `core.host.generate_token`, `core.host.revoke_token` and `core.host.create_config` are removed.
|
||||
Check `core.host.approve` and `core.host.revoke` instead.
|
||||
- `clusteriocontroller bootstrap generate-host-token` is removed, scripts that set up hosts can start the host with `--user-token` to approve it with a user token.
|
||||
|
||||
Host records are no longer created when a host connects, only by approving it, and the controller rejects hosts it has no record of.
|
||||
Revoking a host deletes its record and note.
|
||||
Plugins that keep data per host should remove it when the host is deleted.
|
||||
On the controller the `update` event of `controller.hosts.records` gives the record with `isDeleted` set to true, and subscribers of `HostUpdatesEvent` receive the host with `isDeleted` set to true.
|
||||
A host that is revoked and approved again gets a new id.
|
||||
|
||||
|
||||
## Host manager
|
||||
|
||||
`controller.hosts` is now a `HostManager`, like `controller.users` is a `UserManager`.
|
||||
`get`, `getMutable`, `has` and `values` work as before.
|
||||
Everything else on the datastore, like `set`, `delete`, `size` and the `update` event, is on `controller.hosts.records`.
|
||||
|
||||
The host manager also signs and checks host tokens and creates and deletes hosts:
|
||||
|
||||
- `controller.generateHostToken(hostId)` is now `controller.hosts.signHostToken(hostId)`.
|
||||
- `controller.verifyHostToken(token)` is now `controller.hosts.verifyHostToken(token)`.
|
||||
It returns the `HostRecord` instead of the host id.
|
||||
- `controller.hostPairing.createHost(name)` is now `controller.hosts.createHost(name)`.
|
||||
It returns the new `HostRecord` instead of `{ hostId, token, name }`, sign a token for it with `signHostToken`.
|
||||
- `controller.hosts.revokeHost(hostId, revokedBy)` deletes a host the same way `HostRevokeRequest` does.
|
||||
|
||||
User tokens are checked with `controller.users.verifyUserToken(token)`, which returns the user or throws if the token is invalid.
|
||||
@@ -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
|
||||
+64
-2
@@ -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.
|
||||
@@ -32,6 +32,63 @@ The [send-buffer setting](../configuration.md#controllermax_send_buffer_size) co
|
||||

|
||||
|
||||
|
||||
## Host pairing
|
||||
|
||||
The host id and token sent in `registerHost` are requested by the host over HTTP the first time it starts, before it connects.
|
||||
Hosts are only added to the controller by approving a pairing request, and `registerHost` is rejected with close code 3000 (Unauthorized) for a host id the controller has no record of.
|
||||
Revoking a host deletes its record, so its token stops working and the host has to be approved again the next time it starts, which gives it a new id.
|
||||
See [Setting up remote hosts](/README.md#setting-up-remote-hosts) for how this looks to the user.
|
||||
|
||||
The endpoints below take and return JSON bodies and are sent with `Cache-Control: no-store`.
|
||||
The `POST` endpoints return errors as `{"error": "<message>"}` and respond with 503 while the controller is in recovery mode.
|
||||
A request body that is not valid JSON or is larger than 4 kB is rejected with 400 or 413 before it reaches the endpoint, without a JSON body.
|
||||
`GET /api/host-pairing/check` also works in recovery mode, and responds to a token that is not valid with a plain 401 without a JSON body.
|
||||
A user or host token is sent in either an `Authorization: Bearer <token>` header or an `X-Access-Token` header.
|
||||
|
||||
### `POST /api/host-pairing`
|
||||
|
||||
Creates a request for a host to join the cluster.
|
||||
|
||||
- `name: string` - Name of the host, at most 100 characters after trimming whitespace, without control characters.
|
||||
- `version: string` (optional) - Version of the host.
|
||||
|
||||
Responds with 202 and `{"requestId": string, "code": string}`.
|
||||
The `code` is shown to the user to approve the request with, formatted as six characters like `ABC-DEF`.
|
||||
Codes are matched ignoring case and anything that is not a letter or digit, so `abcdef` matches `ABC-DEF`.
|
||||
The `requestId` is a secret used to poll for the result, it is never shown to users.
|
||||
|
||||
If a user token is sent and the user has the `core.host.approve` permission the host is created right away and the response is 200 with the same body as an approved poll.
|
||||
An invalid token gives 401 and a user without the permission gives 403, a token is never ignored to create a pending request instead.
|
||||
|
||||
A missing or too long name gives 400.
|
||||
Too many pending requests from the same address, or in total as set by [controller.host_pairing_max_pending](/docs/configuration.md#controllerhost_pairing_max_pending), gives 429 with a `Retry-After` header in seconds.
|
||||
|
||||
### `POST /api/host-pairing/poll`
|
||||
|
||||
- `requestId: string` - Id returned when the request was created.
|
||||
|
||||
Responds with 202 and `{"status": "pending"}` while the request is waiting for approval.
|
||||
Once approved it responds with 200 and `{"hostId": integer, "token": string, "name": string}`, where `name` is the name the host was approved with, which can differ from the one asked for.
|
||||
Rejected requests give 403, and unknown or expired requests give 404.
|
||||
The result of an approved or rejected request is only returned once, after which the request is gone.
|
||||
|
||||
A pending request expires 30 seconds after it was last polled, and after waiting for the time set by [controller.host_pairing_timeout](/docs/configuration.md#controllerhost_pairing_timeout).
|
||||
The host polls every 2 seconds, and makes a new request when the previous one has expired.
|
||||
|
||||
### `POST /api/host-pairing/cancel`
|
||||
|
||||
- `requestId: string` - Id returned when the request was created.
|
||||
|
||||
Removes a pending request, sent by the host when it stops waiting.
|
||||
Responds with 204 whether or not the request existed.
|
||||
|
||||
### `GET /api/host-pairing/check`
|
||||
|
||||
Checks a host token.
|
||||
Responds with 200 and `{"valid": true}` if the token is valid and the host it was issued to still exists, and with 401 otherwise.
|
||||
A host with a saved token checks it with this when it starts, and requests to join again if the token is not accepted.
|
||||
|
||||
|
||||
## Connector flow
|
||||
|
||||
To manage the complexity of connecting, reconnecting, resuming or invalidating dropped sessions the WebSocket connection for a `Link` class is managed by a connector.
|
||||
@@ -54,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.
|
||||
|
||||

|
||||
|
||||
@@ -119,6 +176,11 @@ Host handshake for establishing a new connection session.
|
||||
- `plugins: Object<string, string>` -
|
||||
Object mapping plugin names to plugin version for plugins that are available on the host.
|
||||
|
||||
The controller closes the connection with code 3000 (Unauthorized) if the token is invalid, was issued for another id, or if there is no host with this id, see [Host pairing](#host-pairing).
|
||||
The host checks its token before connecting and requests to join again if it is not accepted, so this normally only happens to a host that is already running.
|
||||
A host that has been rejected exits with code 8, and the run scripts created by the installer do not restart it.
|
||||
A host that is revoked while connected is disconnected, is rejected when it tries to connect again, and shuts down.
|
||||
|
||||
#### `registerControl`
|
||||
|
||||
Control handshake for enstablishing a new connection session.
|
||||
|
||||
@@ -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
|
||||
@@ -16,6 +16,7 @@ Each entrypoint of a plugin exports a function that attaches handlers to hooks c
|
||||
- [Defining Link Messages](#defining-link-messages)
|
||||
- [Sending Link Messages](#sending-link-messages)
|
||||
- [Handling connection events](#handling-connection-events)
|
||||
- [Web Pages for a Single Resource](#web-pages-for-a-single-resource)
|
||||
- [Collecting Statistics](#collecting-statistics)
|
||||
- [Adding Custom Commands to clusterioctl](#adding-custom-commands-to-clusterioctl)
|
||||
|
||||
@@ -43,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.
|
||||
@@ -150,6 +151,10 @@ The following properties are recognized:
|
||||
Array of features the plugin needs from the instances it is loaded on, any of `"SavePatching"`, `"ScriptCommands"` and `"LuaUdp"`.
|
||||
See [Handling Invalid Configuration](#handling-invalid-configuration)
|
||||
|
||||
**requiredMods**:
|
||||
Array of Factorio mods the plugin needs in the mod pack of the instances it is loaded on, written as Factorio dependency strings.
|
||||
See [Handling Invalid Configuration](#handling-invalid-configuration)
|
||||
|
||||
**messages**:
|
||||
Array of request and event classes for this plugin.
|
||||
See guide for [defining link messages](#defining-link-messages) below.
|
||||
@@ -201,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`.
|
||||
@@ -211,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
|
||||
@@ -318,6 +353,26 @@ export const plugin = {
|
||||
```
|
||||
|
||||
Enabling the plugin on an instance that has the feature turned off then fails config validation, so the mistake is caught when the config is edited instead of when the instance starts.
|
||||
Instances that have the feature turned off get the plugin disabled by default when it is added.
|
||||
|
||||
If the plugin talks to a Factorio mod, list the mod under `requiredMods` using the same format as `dependencies` in a mod's info.json, without a prefix.
|
||||
List a mod twice to give a version range:
|
||||
|
||||
```js
|
||||
export const plugin = {
|
||||
name: "foo_frobber",
|
||||
// ...
|
||||
requiredMods: ["frobber >= 1.2.0", "frobber < 2.0.0"],
|
||||
};
|
||||
```
|
||||
|
||||
An instance with the plugin loaded refuses to start if its mod pack is missing one of the mods, has it disabled, or has a version outside the range.
|
||||
Leave out the dependencies of the required mods. Factorio checks those itself.
|
||||
When the controller starts it downloads required mods it does not have, and their dependencies, from the mod portal for the Factorio version of the default mod pack.
|
||||
This needs `controller.factorio_username` and `controller.factorio_token` to be set.
|
||||
The mods still have to be added to the mod packs by hand.
|
||||
|
||||
Forks of a required mod are not supported.
|
||||
|
||||
Other constraints on config fields are expressed with a `validator` on the field definition, which throws when the value is not acceptable.
|
||||
Use `dependsOn` when the check involves other fields so that the validator runs when those change too.
|
||||
@@ -842,6 +897,34 @@ This means that if your plugin sends a lot of events or requests, they can end u
|
||||
To avoid this you should be throtteling and/or stopping your requests/events after `drop` has been raised, and continue back as normal when `resume` is raised.
|
||||
|
||||
|
||||
## Web Pages for a Single Resource
|
||||
|
||||
A web page showing one resource from a subscription has more to handle than the resource itself.
|
||||
It can still be loading, it might not exist, it can be deleted while the page is open, and the subscription is rejected if the user lacks the permission for it.
|
||||
`useResourceState` and `ResourceState` from `@clusterio/web_ui` show these the same way as the pages for hosts, instances and the other built in resources.
|
||||
|
||||
```tsx
|
||||
function FrobberPage() {
|
||||
const id = Number(useParams().id);
|
||||
const [frobbers, synced, error] = useSyncExternalStore(subscribe, () => frobberSubscriber.getSnapshot());
|
||||
const frobber = frobbers.get(id);
|
||||
const state = useResourceState(frobber, synced, error, id);
|
||||
|
||||
const nav = [{ name: "Frobbers", path: "/frobbers" }, { name: frobber?.name ?? String(id) }];
|
||||
if (!frobber) {
|
||||
return <ResourceState state={state} type="Frobber" id={id} nav={nav} listPath="/frobbers" error={error} />;
|
||||
}
|
||||
|
||||
return <PageLayout nav={nav}>{frobber.name}</PageLayout>;
|
||||
}
|
||||
```
|
||||
|
||||
`useResourceState` returns `"ok"` when there is a value and otherwise `"loading"`, `"missing"`, `"deleted"` or `"error"`.
|
||||
It tells deleted from missing by remembering if it has seen a value for that id.
|
||||
`ResourceState` renders the whole page for the states without a value, with a link back to the page at `listPath`.
|
||||
The `useHost`, `useInstance`, `useUser`, `useRole` and `useModPack` hooks return `[value, synced, error]` so they can be used the same way.
|
||||
|
||||
|
||||
## Collecting Statistics
|
||||
|
||||
Clusterio comes with its own Prometheus client implementation, one part due to Not Invented Here and another part due to collectors in prom-client being difficult to get to work nicely with collecting data from plugins optionally loaded at runtime on different computers.
|
||||
@@ -942,6 +1025,20 @@ For a command the `definition` is the arguments to pass to [yargs.command](http:
|
||||
The `handler` is an async function that's invoked when the command is executed and it's passed the parsed command line arguments and a reference to the `Ctl` class of clusterioctl.
|
||||
Note that messages sent from clusterioctl needs to have `"control"` as a part of `src` for it to be accepted by the controller, see [Defining Link Messages](#defining-link-messages) for how to define the messages that can be sent to the controller.
|
||||
|
||||
Commands print their results through `ctl.output` so that `--output json` works for them:
|
||||
|
||||
```js
|
||||
handler: async function(args, ctl) {
|
||||
const result = await ctl.sendTo("controller", new messages.FrobnicateRequest(args.type));
|
||||
ctl.output.result(result, () => console.log(`Frobnicated ${result.count} foos`));
|
||||
},
|
||||
```
|
||||
|
||||
`ctl.output.result(data, human)` prints `data` as JSON in json and wire mode and calls `human` otherwise.
|
||||
`ctl.output.table(rows, map)` prints an array of objects as a JSON array, or as a table in human mode with `map` applied to each row first.
|
||||
`ctl.output.human` is true when the output is meant for reading.
|
||||
Commands that print nothing get `Command ran successfully` or `{"success": true}` printed for them, and errors thrown from the handler are printed as `{"error": "<ClassName>", "message": "<message>"}` in json and wire mode.
|
||||
|
||||
To have the command tree become part of clusterioctl it needs to be added to the rootCommand tree in the `addCommands` hook of the ctl entrypoint:
|
||||
|
||||
```js
|
||||
@@ -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
|
||||
@@ -27,6 +27,7 @@ The save patching is based on the built in [event_handler](https://github.com/wu
|
||||
Mods on the other hand work without modifications.
|
||||
|
||||
This can be disabled with the `factorio.enable_save_patching` config on a per instance basis, however disabling it means that modules are not loaded into the game and most plugins will not function.
|
||||
A save that was patched before has its modules removed again when it's started with save patching disabled.
|
||||
To use the modules outside of Clusterio the `npx clusteriohost create-scenario` command creates a scenario with the modules patched into it.
|
||||
Note that the IPC between the game and the host is not available outside of Clusterio, so modules that depend on it will not work as expected in such a scenario.
|
||||
|
||||
|
||||
+137
-295
@@ -1,368 +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]`.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Logging in
|
||||
|
||||
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
|
||||
|
||||
npx clusteriocontroller bootstrap generate-user-token <username>
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
### Generate token
|
||||
|
||||
ctl> host generate-token [--id <host id>]
|
||||
|
||||
Generate a token for a host. `--id` is the host id.
|
||||
|
||||
### Create config
|
||||
|
||||
ctl> host create-config [--id <host id>] [--name <host name>] [--generate-token <bool>] [--output <path to output>]
|
||||
|
||||
Create a host config. `--id` id the host id. `--name` is the host name. `--generate-token` decides whether to also generate a token, defaulting to `0`. `--output` is the filename for the output of the config; Default is "config-host.json", "-" for stdout.
|
||||
|
||||
### 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
|
||||
### Creating an instance
|
||||
|
||||
List instances.
|
||||
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>]
|
||||
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.
|
||||
### 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.
|
||||
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.
|
||||
|
||||
#### Edit instance config
|
||||
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 edit <instance> [editor]
|
||||
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.
|
||||
|
||||
Edit instance config in a text editor. Once file is saved and editor has been exited, 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
|
||||
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 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.
|
||||
Mod packs can be shared between clusters with Export to string on the mod pack page and Import string on the Mods page.
|
||||
|
||||
## Users
|
||||
ctl: [Mods](clusterioctl.md#mods), [Mod Packs](clusterioctl.md#mod-packs).
|
||||
|
||||
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.
|
||||
### Exporting data
|
||||
|
||||
### List users
|
||||
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.
|
||||
|
||||
ctl> user list
|
||||
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.
|
||||
|
||||
Lists all user accounts in the cluster along with some data for each.
|
||||

|
||||
|
||||
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.
|
||||
|
||||
### Create User
|
||||
The Icon reference link under Inspect exported data on the mod pack page shows everything in the export.
|
||||
|
||||
ctl> user create <name>
|
||||
ctl: [Export data](clusterioctl.md#export-data).
|
||||
|
||||
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.
|
||||
|
||||
## Users and Permissions
|
||||
|
||||
### Promote User to Server Admin
|
||||
### Players
|
||||
|
||||
ctl> user set-admin <name> [--revoke] [--create]
|
||||
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.
|
||||
|
||||
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.
|
||||
Existing Factorio admin, ban and whitelist files can be imported with Bulk Actions on the Users page, which can also export them.
|
||||
|
||||
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.
|
||||
ctl: [Users](clusterioctl.md#users).
|
||||
|
||||
**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.
|
||||
### Granting access to the cluster
|
||||
|
||||
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.
|
||||
|
||||
### Whitelist User
|
||||
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.
|
||||
|
||||
ctl> user set-whitelisted <name> [--remove] [--create]
|
||||
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.
|
||||
|
||||
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.
|
||||
The user can then log in as described in [Logging in](#logging-in).
|
||||
|
||||
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.
|
||||
ctl: [Roles](clusterioctl.md#roles), [Set Cluster Roles](clusterioctl.md#set-cluster-roles).
|
||||
|
||||
|
||||
### Ban User
|
||||
## Plugins and Updates
|
||||
|
||||
ctl> user set-banned <name> [--reason <message>] [--pardon] [--create]
|
||||
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.
|
||||
|
||||
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.
|
||||
Plugins can also be installed on the computer itself, see [Installing Plugins](/README.md#installing-plugins).
|
||||
|
||||
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.
|
||||
## Logs
|
||||
|
||||
### Bulk importing admin, whitelist and ban lists
|
||||
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.
|
||||
|
||||
Whitelists and admin lists can be bulk imported with the following commands:
|
||||
|
||||
ctl> user whitelist-bulk-import <file> [--create]
|
||||
ctl> user admin-bulk-import <file> [--create]
|
||||
|
||||
The file should simply be newline seperated names:
|
||||
|
||||
joe
|
||||
bob
|
||||
allan
|
||||
|
||||
The `--create` option will create the user if they do not exist, and then set the relevent value.
|
||||
|
||||
Banlists can be bulk imported with the following command:
|
||||
|
||||
ctl> user banned-bulk-import <file> [--create]
|
||||
|
||||
The file should be names, followed by a ban reason:
|
||||
|
||||
joe greifed copper mines
|
||||
bob stole materials
|
||||
allan rude language
|
||||
|
||||
The first string on the line is used as the username, the others are used as the ban reason.
|
||||
The `--create` option will create the user if they do not exist, then ban them.
|
||||
|
||||
### 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)
|
||||
|
||||
By default, remote updates are enabled unless you selected "no" during installation.
|
||||
Remote updates allow ctl and the web UI to update plugins on machines within the cluster.
|
||||
However, remote installations are disabled by default to prevent the risk of arbitrary code execution through the installation of malicious npm packages onto the machine. See below if you wish to enable this feature.
|
||||
|
||||
### 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).
|
||||
@@ -19,6 +19,12 @@ Additianlly WebSocket connections to `/api/socket` also needs to be forwarded.
|
||||
Typically this requires explicit configuration and support for forwarding WebSocket connections.
|
||||
If the interface hosted under a sub-path the `/api/socket` address is relative to the sub-path and the sub-path also needs to be stripped out when forwarded.
|
||||
|
||||
Saves are sent from hosts to the web interface through the controller as they are uploaded to `/api/stream/`.
|
||||
If the proxy buffers request bodies it holds back a host's upload until all of it has arrived.
|
||||
A save that takes longer than `controller.proxy_stream_timeout` to upload then fails, after the whole save was sent.
|
||||
Turn request buffering off for the proxy, with Nginx this is `proxy_request_buffering off;`.
|
||||
Nginx also limits request bodies to 1 MB by default, set `client_max_body_size` high enough for the saves and mods you upload.
|
||||
|
||||
You can also optionally set the controller to listen only on the loopback interface to prevent it being directly connected to from the outside.
|
||||
|
||||
npx clusteriocontroller config set controller.bind_address 127.0.0.1
|
||||
@@ -63,7 +69,7 @@ This creates a private key file named `key.pem` and a public certificate file na
|
||||
npx clusteriocontroller config set controller.tls_certificate cert.pem
|
||||
npx clusteriocontroller config set controller.tls_private_key key.pem
|
||||
|
||||
Additionally you will need copy the `cert.pem` file to all of the computers you want to set up as hosts and configure node to trust it by setting the `NODE_EXTRA_CA_CERTS` environment variable to a path to this file before the host is started. You can do this by passing `--self-signed-cert path/to/cert` to the installer when setting up a host, or manually by editing run-host.cmd, run-host.sh and/or clusteriohost.service by adding the following line next to the one setting `NODE_OPTIONS`:
|
||||
Additionally you will need copy the `cert.pem` file to all of the computers you want to set up as hosts and configure node to trust it by setting the `NODE_EXTRA_CA_CERTS` environment variable to a path to this file before the host is started. You can do this by passing `--self-signed-cert path/to/cert` to the installer when setting up a host, which also makes the installer trust the certificate when it asks the controller to approve the host, or manually by editing run-host.cmd, run-host.sh and/or clusteriohost.service by adding the following line next to the one setting `NODE_OPTIONS`:
|
||||
|
||||
**For run-host.cmd**
|
||||
|
||||
|
||||
+5
-6
@@ -8,8 +8,8 @@
|
||||
"build": "tsc --build",
|
||||
"watch": "tsc --build --watch",
|
||||
"build-mod": "pnpm run -r build-mod --output-dir ../../dist",
|
||||
"test": "pnpm run build && NODE_EXTRA_CA_CERTS=$(pwd)/test/file/tls/cert.pem mocha --enable-source-maps --check-leaks -R spec --recursive test \"plugins/*/test/**\" --exclude \"test/manual/**\"",
|
||||
"silent-test": "SILENT_TEST=y pnpm test",
|
||||
"test": "pnpm run build && NODE_EXTRA_CA_CERTS=$(pwd)/test/file/tls/cert.pem mocha --enable-source-maps --check-leaks -R ./test/reporter.cjs --recursive test \"plugins/*/test/**\" --exclude \"test/manual/**\"",
|
||||
"silent-test": "TEST_OUTPUT=silent pnpm test",
|
||||
"fast-test": "FAST_TEST=y pnpm test",
|
||||
"no-external-test": "NO_EXTERNAL_TEST=y pnpm test",
|
||||
"cover": "c8 pnpm test",
|
||||
@@ -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": {
|
||||
@@ -28,7 +28,7 @@
|
||||
]
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
"node": "^22.18.0 || >=24.2.0"
|
||||
},
|
||||
"workspaces": [
|
||||
"packages/*",
|
||||
@@ -46,9 +46,8 @@
|
||||
"@types/node": "catalog:",
|
||||
"c8": "^12.0.0",
|
||||
"express": "catalog:",
|
||||
"form-data": "^4.0.6",
|
||||
"jsonwebtoken": "catalog:",
|
||||
"mocha": "^11.8.0",
|
||||
"mocha": "^12.0.3",
|
||||
"oxlint": "^1.88.0",
|
||||
"typescript": "catalog:",
|
||||
"yargs": "catalog:",
|
||||
|
||||
@@ -21,15 +21,15 @@ import crypto from "crypto";
|
||||
import yargs from "yargs";
|
||||
import util from "util";
|
||||
import winston from "winston";
|
||||
import DailyRotateFile from "winston-daily-rotate-file";
|
||||
|
||||
import jwt from "jsonwebtoken";
|
||||
|
||||
// homebrew modules
|
||||
// Reduce startup time by lazy compiling schemas.
|
||||
import "./src/set_lazy_schema_compilation.js";
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { ConsoleTransport, levels, logger } from "@clusterio/lib";
|
||||
|
||||
import Controller from "./src/Controller.js";
|
||||
import type Controller from "./src/Controller.js";
|
||||
import UserManager from "./src/UserManager.js";
|
||||
import UserRecord from "./src/UserRecord.js";
|
||||
import packageConfig from "@clusterio/controller/package.json" with { type: "json" };
|
||||
@@ -186,14 +186,6 @@ async function handleBootstrapCommand(
|
||||
// eslint-disable-next-line no-console
|
||||
console.log(userManager.signUserToken(user));
|
||||
|
||||
} else if (subCommand === "generate-host-token") {
|
||||
// eslint-disable-next-line no-console
|
||||
console.log(jwt.sign(
|
||||
{ aud: "host", host: args.id },
|
||||
// Auth secret is never null after startup
|
||||
Buffer.from(controllerConfig.get("controller.auth_secret")!, "base64")
|
||||
));
|
||||
|
||||
} else if (subCommand === "create-ctl-config") {
|
||||
let admin = userManager.getByName(args.name);
|
||||
if (!admin) {
|
||||
@@ -203,6 +195,7 @@ async function handleBootstrapCommand(
|
||||
}
|
||||
let ctlConfig = new lib.CtlConfig("control");
|
||||
|
||||
const { default: Controller } = await import("./src/Controller.js");
|
||||
ctlConfig.set("ctl.controller_url", Controller.calculateControllerUrl(controllerConfig));
|
||||
ctlConfig.set(
|
||||
"ctl.controller_token",
|
||||
@@ -215,7 +208,7 @@ async function handleBootstrapCommand(
|
||||
console.log(content);
|
||||
} else {
|
||||
logger.info(`Writing ${args.output}`);
|
||||
await lib.safeOutputFile(args.output, content, { mode: 0o600 });
|
||||
await lib.atomicOverwriteFile(args.output, content, { mode: 0o600 });
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -322,9 +315,6 @@ async function initialize(): Promise<InitializeParameters> {
|
||||
.command("generate-user-token <name>", "Generate authentication token for the given user", yargs => {
|
||||
yargs.positional("name", { describe: "Name of the user", type: "string" });
|
||||
})
|
||||
.command("generate-host-token <id>", "Generate authentication token for the given host", yargs => {
|
||||
yargs.positional("id", { describe: "ID of the host", type: "number" });
|
||||
})
|
||||
.command("create-ctl-config <name>", "Create clusterioctl config for the given user", yargs => {
|
||||
yargs.option("output", {
|
||||
describe: "Path to output config (- for stdout)", type: "string",
|
||||
@@ -364,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,
|
||||
@@ -475,6 +463,8 @@ async function startup() {
|
||||
return;
|
||||
}
|
||||
|
||||
// Loaded here as the server is not needed by the other commands
|
||||
const { default: Controller } = await import("./src/Controller.js");
|
||||
controller = await Controller.fromConfig(
|
||||
controllerConfig,
|
||||
pluginInfos,
|
||||
@@ -499,6 +489,11 @@ async function startup() {
|
||||
controller.stop();
|
||||
});
|
||||
|
||||
lib.startLogRetention(
|
||||
[path.join(args.logDirectory, "cluster"), path.join(args.logDirectory, "controller")],
|
||||
() => controllerConfig.get("controller.log_retention_days"),
|
||||
);
|
||||
|
||||
await controller.start(args);
|
||||
}
|
||||
|
||||
|
||||
@@ -5,7 +5,9 @@ export { default as ControlConnection } from "./src/ControlConnection.js";
|
||||
export { default as HostConnection } from "./src/HostConnection.js";
|
||||
export { default as InstanceRecord } from "./src/InstanceRecord.js";
|
||||
export { default as InstanceManager } from "./src/InstanceManager.js";
|
||||
export { default as HostManager } from "./src/HostManager.js";
|
||||
export { default as HostRecord } from "./src/HostRecord.js";
|
||||
export { default as HostPairingManager, HostPairingError } from "./src/HostPairingManager.js";
|
||||
export { BaseControllerPlugin, ControllerHooks, type ControllerPluginContext } from "./src/BaseControllerPlugin.js";
|
||||
export { default as UserManager } from "./src/UserManager.js";
|
||||
export { default as UserRecord } from "./src/UserRecord.js";
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@clusterio/controller",
|
||||
"version": "2.0.3",
|
||||
"version": "2.1.2",
|
||||
"description": "Implementation of Clusterio controller",
|
||||
"homepage": "https://github.com/clusterio/clusterio#readme",
|
||||
"author": "Hornwitser <github@hornwitser.no>",
|
||||
@@ -32,7 +32,7 @@
|
||||
"clusteriocontroller": "./dist/node/controller.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
"node": "^22.18.0 || >=24.2.0"
|
||||
},
|
||||
|
||||
"dependencies": {
|
||||
@@ -45,7 +45,6 @@
|
||||
"jsonwebtoken": "catalog:",
|
||||
"semver": "catalog:",
|
||||
"winston": "catalog:",
|
||||
"winston-daily-rotate-file": "catalog:",
|
||||
"ws": "catalog:",
|
||||
"yargs": "catalog:"
|
||||
},
|
||||
|
||||
@@ -8,6 +8,7 @@ import { logFilter, logger } from "@clusterio/lib";
|
||||
import BaseConnection from "./BaseConnection.js";
|
||||
import User from "./User.js";
|
||||
import UserRecord from "./UserRecord.js";
|
||||
import type InstanceRecord from "./InstanceRecord.js";
|
||||
import * as routes from "./routes.js";
|
||||
import Controller from "./Controller.js";
|
||||
|
||||
@@ -81,10 +82,11 @@ export default class ControlConnection extends BaseConnection {
|
||||
this.handle(lib.ControllerConfigSetRequest, this.handleControllerConfigSetRequest.bind(this));
|
||||
this.handle(lib.ControllerConfigSetFieldRequest, this.handleControllerConfigSetFieldRequest.bind(this));
|
||||
this.handle(lib.ControllerConfigSetPropRequest, this.handleControllerConfigSetPropRequest.bind(this));
|
||||
this.handle(lib.HostRevokeTokensRequest, this.handleHostRevokeTokensRequest.bind(this));
|
||||
this.handle(lib.HostRevokeRequest, this.handleHostRevokeRequest.bind(this));
|
||||
this.handle(lib.HostListRequest, this.handleHostListRequest.bind(this));
|
||||
this.handle(lib.HostGenerateTokenRequest, this.handleHostGenerateTokenRequest.bind(this));
|
||||
this.handle(lib.HostConfigCreateRequest, this.handleHostConfigCreateRequest.bind(this));
|
||||
this.handle(lib.HostPairingListRequest, this.handleHostPairingListRequest.bind(this));
|
||||
this.handle(lib.HostPairingApproveRequest, this.handleHostPairingApproveRequest.bind(this));
|
||||
this.handle(lib.HostPairingRejectRequest, this.handleHostPairingRejectRequest.bind(this));
|
||||
this.handle(lib.InstanceDetailsGetRequest, this.handleInstanceDetailsGetRequest.bind(this));
|
||||
this.handle(lib.InstanceDetailsListRequest, this.handleInstanceDetailsListRequest.bind(this));
|
||||
this.handle(lib.InstanceCreateRequest, this.handleInstanceCreateRequest.bind(this));
|
||||
@@ -93,6 +95,7 @@ export default class ControlConnection extends BaseConnection {
|
||||
this.handle(lib.InstanceConfigSetRequest, this.handleInstanceConfigSetRequest.bind(this));
|
||||
this.handle(lib.InstanceConfigSetFieldRequest, this.handleInstanceConfigSetFieldRequest.bind(this));
|
||||
this.handle(lib.InstanceConfigSetPropRequest, this.handleInstanceConfigSetPropRequest.bind(this));
|
||||
this.handle(lib.InstanceConfigInheritFieldRequest, this.handleInstanceConfigInheritFieldRequest.bind(this));
|
||||
this.handle(lib.InstanceAssignRequest, this.handleInstanceAssignRequest.bind(this));
|
||||
this.handle(lib.InstanceSaveDetailsListRequest, this.handleInstanceSaveDetailsListRequest.bind(this));
|
||||
this.handle(lib.InstanceRenameSaveRequest, controller.sendRequestToHostByInstanceId.bind(controller));
|
||||
@@ -248,49 +251,25 @@ export default class ControlConnection extends BaseConnection {
|
||||
this._controller.config.setProp(field as keyof lib.ControllerConfigFields, prop, value, "control");
|
||||
}
|
||||
|
||||
async handleHostRevokeTokensRequest(request: lib.HostRevokeTokensRequest) {
|
||||
const host = this._controller.hosts.getMutable(request.hostId);
|
||||
if (!host) {
|
||||
throw new Error(`Unknown host id (${request.hostId})`);
|
||||
}
|
||||
|
||||
host.tokenValidAfter = Math.floor(Date.now() / 1000);
|
||||
|
||||
const hostConnection = this._controller.wsServer.hostConnections.get(request.hostId);
|
||||
if (hostConnection) {
|
||||
hostConnection.connector.terminate();
|
||||
}
|
||||
|
||||
this._controller.hosts.set(host);
|
||||
async handleHostRevokeRequest(request: lib.HostRevokeRequest) {
|
||||
await this._controller.hosts.revokeHost(request.hostId, this.user.name);
|
||||
}
|
||||
|
||||
async handleHostListRequest(): Promise<lib.HostDetails[]> {
|
||||
return [...this._controller.hosts.values()].map(host => host.toHostDetails());
|
||||
}
|
||||
|
||||
async handleHostGenerateTokenRequest(message: lib.HostGenerateTokenRequest) {
|
||||
let hostId = message.hostId;
|
||||
if (hostId === undefined) {
|
||||
hostId = Math.random() * 2**31 | 0;
|
||||
}
|
||||
return this._controller.generateHostToken(hostId);
|
||||
async handleHostPairingListRequest(): Promise<lib.HostPairingDetails[]> {
|
||||
this._controller.hostPairing.prune();
|
||||
return [...this._controller.hostPairing.records.values()];
|
||||
}
|
||||
|
||||
async handleHostConfigCreateRequest(request: lib.HostConfigCreateRequest) {
|
||||
const hostConfig = new lib.HostConfig("host");
|
||||
async handleHostPairingApproveRequest(request: lib.HostPairingApproveRequest) {
|
||||
return this._controller.hostPairing.approve(request.code, request.name, this.user.name);
|
||||
}
|
||||
|
||||
hostConfig.set("host.controller_url", this._controller.getControllerUrl());
|
||||
if (request.id !== undefined) {
|
||||
hostConfig.set("host.id", request.id);
|
||||
}
|
||||
if (request.name !== undefined) {
|
||||
hostConfig.set("host.name", request.name);
|
||||
}
|
||||
if (request.generateToken) {
|
||||
this.user.checkPermission("core.host.generate_token");
|
||||
hostConfig.set("host.controller_token", this._controller.generateHostToken(hostConfig.get("host.id")));
|
||||
}
|
||||
return hostConfig.toJSON();
|
||||
async handleHostPairingRejectRequest(request: lib.HostPairingRejectRequest) {
|
||||
this._controller.hostPairing.reject(request.code, this.user.name);
|
||||
}
|
||||
|
||||
async handleInstanceDetailsGetRequest(request: lib.InstanceDetailsGetRequest) {
|
||||
@@ -315,6 +294,12 @@ export default class ControlConnection extends BaseConnection {
|
||||
instanceConfig.set("instance.assigned_host", null); // New instances are unassigned
|
||||
}
|
||||
instanceConfig.update(request.config, false, "control");
|
||||
this._controller.instances.checkInheritance(
|
||||
instanceConfig, instanceConfig.get("instance.is_template"), instanceConfig.get("instance.template_id")
|
||||
);
|
||||
if (Object.hasOwn(request.config, "instance.template_id")) {
|
||||
this._controller.instances.applyTemplate(instanceConfig, Object.keys(request.config));
|
||||
}
|
||||
await this._controller.instances.createInstance(instanceConfig);
|
||||
}
|
||||
|
||||
@@ -355,17 +340,41 @@ export default class ControlConnection extends BaseConnection {
|
||||
}
|
||||
}
|
||||
|
||||
this.checkStagedInheritance(instance);
|
||||
instance.config.commitStaging();
|
||||
for (const [fieldName, fieldValue] of Object.entries(request.fields)) {
|
||||
const props = typeof fieldValue === "object"
|
||||
? Object.keys(fieldValue).filter(prop => fieldValue[prop] !== undefined)
|
||||
: undefined;
|
||||
this._controller.instances.overrideField(instance, fieldName, props);
|
||||
}
|
||||
await this._controller.instanceConfigUpdated(instance);
|
||||
} finally {
|
||||
instance.config.revertStaging();
|
||||
}
|
||||
}
|
||||
|
||||
private checkStagedInheritance(instance: InstanceRecord) {
|
||||
const staged = instance.config.staging;
|
||||
this._controller.instances.checkInheritance(
|
||||
instance.config, staged.get("instance.is_template"), staged.get("instance.template_id")
|
||||
);
|
||||
}
|
||||
|
||||
async handleInstanceConfigSetFieldRequest(request: lib.InstanceConfigSetFieldRequest) {
|
||||
const instance = this._controller.instances.getForRequest(request.instanceId);
|
||||
ControlConnection.validateInstanceConfigSetField(request.field);
|
||||
instance.config.set(request.field as keyof lib.InstanceConfigFields, request.value, "control");
|
||||
const field = request.field as keyof lib.InstanceConfigFields;
|
||||
ControlConnection.validateInstanceConfigSetField(field);
|
||||
if (["instance.is_template", "instance.template_id"].includes(field)) {
|
||||
try {
|
||||
instance.config.stage(field, request.value, "control");
|
||||
this.checkStagedInheritance(instance);
|
||||
} finally {
|
||||
instance.config.revertStaging();
|
||||
}
|
||||
}
|
||||
instance.config.set(field, request.value, "control");
|
||||
this._controller.instances.overrideField(instance, field);
|
||||
await this._controller.instanceConfigUpdated(instance);
|
||||
}
|
||||
|
||||
@@ -374,9 +383,18 @@ export default class ControlConnection extends BaseConnection {
|
||||
let { field, prop, value } = request;
|
||||
ControlConnection.validateInstanceConfigSetField(field);
|
||||
instance.config.setProp(field as keyof lib.InstanceConfigFields, prop, value, "control");
|
||||
if (value !== undefined) {
|
||||
this._controller.instances.overrideField(instance, field, [prop]);
|
||||
}
|
||||
await this._controller.instanceConfigUpdated(instance);
|
||||
}
|
||||
|
||||
async handleInstanceConfigInheritFieldRequest(request: lib.InstanceConfigInheritFieldRequest) {
|
||||
ControlConnection.validateInstanceConfigSetField(request.field);
|
||||
this._controller.instances.inheritField(request.instanceId, request.field, request.prop);
|
||||
await this._controller.instanceConfigUpdated(this._controller.instances.getForRequest(request.instanceId));
|
||||
}
|
||||
|
||||
async handleInstanceAssignRequest(request: lib.InstanceAssignRequest) {
|
||||
await this._controller.instances.assignInstance(request.instanceId, request.hostId ?? null);
|
||||
}
|
||||
@@ -613,7 +631,8 @@ export default class ControlConnection extends BaseConnection {
|
||||
* @param request - The request object containing factorioVersion.
|
||||
*/
|
||||
async handleModPortalGetAllRequest(request: lib.ModPortalGetAllRequest) {
|
||||
const cacheKey = `${request.factorioVersion}-${request.hide_deprecated}`;
|
||||
const hideDeprecated = request.hide_deprecated ?? false;
|
||||
const cacheKey = `${request.factorioVersion}-${hideDeprecated}`;
|
||||
const cachedData = this._controller.modPortalCache.get(cacheKey);
|
||||
|
||||
const cacheDuration = this._controller.config.get("controller.mod_portal_cache_duration_minutes") * 60 * 1000;
|
||||
@@ -626,7 +645,7 @@ export default class ControlConnection extends BaseConnection {
|
||||
const mods = await lib.ModStore.fetchAllModsFromPortal(
|
||||
request.factorioVersion,
|
||||
this._controller.config.get("controller.mod_portal_page_size"),
|
||||
request.hide_deprecated
|
||||
hideDeprecated
|
||||
);
|
||||
this._controller.modPortalCache.set(cacheKey, { timestamp: Date.now(), data: mods });
|
||||
// The Response class is defined inline within the Request class
|
||||
@@ -643,36 +662,7 @@ export default class ControlConnection extends BaseConnection {
|
||||
* @param request - Request object with mod name, version, and factorioVersion.
|
||||
*/
|
||||
async handleModPortalDownloadRequest(request: lib.ModPortalDownloadRequest) {
|
||||
const factorioVersion = request.factorioVersion;
|
||||
const toDownload = this._controller.modStore.filterInstalled(request.mods, false);
|
||||
|
||||
if (toDownload.length > 0) {
|
||||
// Get Factorio credentials from config
|
||||
const username = this._controller.config.get("controller.factorio_username");
|
||||
const token = this._controller.config.get("controller.factorio_token");
|
||||
|
||||
if (!username || username === "" || !token || token === "") {
|
||||
throw new lib.ConflictError("Factorio credentials (username, token) not configured on the controller.");
|
||||
}
|
||||
|
||||
try {
|
||||
logger.info(`Downloading ${toDownload.length} mods for Factorio ${factorioVersion} from portal.`);
|
||||
await this._controller.modStore.downloadMods(toDownload, username, token, factorioVersion);
|
||||
|
||||
} catch (error: any) {
|
||||
logger.error(`Error downloading mods from portal: ${error.message}`);
|
||||
const errorMessage = "Mod portal download failed";
|
||||
if (error.message.includes("401") || error.message.includes("Unauthorized")) {
|
||||
throw new lib.ConflictError(
|
||||
`${errorMessage}: Authentication failed. Check Factorio username/token in controller config.`
|
||||
);
|
||||
}
|
||||
if (error.message.includes("404") || error.message.includes("Not Found")) {
|
||||
throw new lib.NotFoundError(`${errorMessage}: Mod version not found on the portal.`);
|
||||
}
|
||||
throw new lib.InternalServerError(`${errorMessage}: ${error.message}`);
|
||||
}
|
||||
}
|
||||
await this._controller.downloadModsFromPortal(request.mods, request.factorioVersion);
|
||||
|
||||
// Verify all mods are present
|
||||
const modInfos = [];
|
||||
@@ -688,183 +678,9 @@ export default class ControlConnection extends BaseConnection {
|
||||
return modInfos;
|
||||
}
|
||||
|
||||
// eslint-disable-next-line complexity
|
||||
async handleModDependencyResolveRequest(request: lib.ModDependencyResolveRequest) {
|
||||
const {factorioVersion, checkForUpdates} = request;
|
||||
const searchQueue = [...request.mods];
|
||||
const localInfos = [...this._controller.modStore.mods()];
|
||||
|
||||
const builtInModNames = lib.ModPack.getBuiltinModNames(factorioVersion);
|
||||
const skipSearch = new Set(builtInModNames);
|
||||
|
||||
type ModPortalModType = InstanceType<typeof lib.ModPortalGetAllRequest.Response>["mods"][number];
|
||||
type ModPortalReleaseType = NonNullable<ModPortalModType["releases"]>[number];
|
||||
const dependencyRequirements = new Map<string, lib.ModVersionRange>();
|
||||
const recommendedRequirements = new Map<string, lib.ModVersionRange>();
|
||||
const optionalRequirements = new Map<string, lib.ModVersionRange>();
|
||||
const candidateReleases = new Map<string, lib.ModInfo>();
|
||||
const errors = new Map<string, lib.ModDependencyResolveErrors>();
|
||||
|
||||
const _modPortalReleases = new Map<string, ModPortalModType | null>();
|
||||
async function fetchModReleases(modName: string) {
|
||||
let releases = _modPortalReleases.get(modName);
|
||||
if (releases === undefined) {
|
||||
try {
|
||||
releases = await lib.ModStore.fetchModReleases(modName);
|
||||
} catch (error: any) {
|
||||
if (!error.message.includes("404") && !error.message.includes("Not Found")) {
|
||||
logger.error(`Error fetching mod from portal: ${error.message}`);
|
||||
throw new lib.InternalServerError(`Dependency resolution failed: ${error.message}`);
|
||||
} else {
|
||||
releases = null;
|
||||
}
|
||||
}
|
||||
}
|
||||
_modPortalReleases.set(modName, releases);
|
||||
return releases;
|
||||
}
|
||||
|
||||
function selectModRelease(releases: ModPortalModType | null, versionRange: lib.ModVersionRange) {
|
||||
if (!releases || !releases.releases) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Select the latest matching version for the mod pack's Factorio version
|
||||
const release = releases.releases
|
||||
.filter(info => (
|
||||
versionRange.testVersion(info.version)
|
||||
&& lib.normaliseMajorMinorVersion(
|
||||
lib.normaliseSourceVersion(info.info_json.factorio_version)
|
||||
) === factorioVersion
|
||||
))
|
||||
.reduce<ModPortalReleaseType | undefined>((max, cur) => (
|
||||
max && lib.integerSourceVersion(max.version) > lib.integerSourceVersion(cur.version) ? max : cur
|
||||
), undefined);
|
||||
|
||||
if (!release) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Create the mod info class from the selected
|
||||
try {
|
||||
return lib.ModInfo.fromJSON({
|
||||
...release.info_json, // includes dependencies
|
||||
sha1: release.sha1,
|
||||
version: release.version,
|
||||
name: releases.name,
|
||||
author: releases.owner,
|
||||
title: releases.title,
|
||||
});
|
||||
} catch {
|
||||
// Can error if there are invalid dependencies
|
||||
errors.set(releases.name, "invalidDependency");
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
while (searchQueue.length > 0) {
|
||||
// Dequeue the next mod, skip if incompatible
|
||||
const mod = searchQueue.shift()!;
|
||||
if (mod.incompatible) {
|
||||
errors.set(mod.name, "incompatible");
|
||||
continue;
|
||||
}
|
||||
|
||||
// Get the current version range (dependencies can be promoted to a stricter requirement)
|
||||
const versionRange =
|
||||
dependencyRequirements.get(mod.name)
|
||||
?? recommendedRequirements.get(mod.name)
|
||||
?? optionalRequirements.get(mod.name)
|
||||
?? new lib.ModVersionRange();
|
||||
|
||||
if (mod.required) {
|
||||
// Add to required, remove from recommended and optional
|
||||
dependencyRequirements.set(mod.name, versionRange);
|
||||
recommendedRequirements.delete(mod.name);
|
||||
optionalRequirements.delete(mod.name);
|
||||
|
||||
} else if (mod.recommended) {
|
||||
// If not required, add to recommended and remove from optional
|
||||
if (!dependencyRequirements.has(mod.name)) {
|
||||
recommendedRequirements.set(mod.name, versionRange);
|
||||
optionalRequirements.delete(mod.name);
|
||||
}
|
||||
|
||||
} else if (
|
||||
!dependencyRequirements.has(mod.name)
|
||||
&& !recommendedRequirements.has(mod.name)
|
||||
) {
|
||||
// If not required or recommended, add to optional
|
||||
optionalRequirements.set(mod.name, versionRange);
|
||||
}
|
||||
|
||||
// Update the version range if needed
|
||||
if (mod.version) {
|
||||
versionRange.combineVersion(mod.version);
|
||||
if (!versionRange.valid) {
|
||||
candidateReleases.delete(mod.name);
|
||||
errors.set(mod.name, "unsatisfiable");
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
// Do not add dependencies for errors, skips, optionals, or valid candidates
|
||||
const existingCandidate = candidateReleases.get(mod.name);
|
||||
if (errors.has(mod.name) || skipSearch.has(mod.name) || optionalRequirements.has(mod.name) || (
|
||||
existingCandidate && versionRange.testVersion(existingCandidate.version)
|
||||
)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check if a local version fits the requirements
|
||||
let candidate = localInfos
|
||||
.filter(info => (
|
||||
info.name === mod.name
|
||||
&& info.factorioVersion === factorioVersion
|
||||
&& versionRange.testVersion(info.version)
|
||||
))
|
||||
.reduce<lib.ModInfo | undefined>((max, cur) => (
|
||||
max && max.integerVersion > cur.integerVersion ? max : cur
|
||||
), undefined);
|
||||
|
||||
// Check if a mod poral version fits the requirements
|
||||
if (!candidate || checkForUpdates) {
|
||||
const releases = await fetchModReleases(mod.name);
|
||||
const release = selectModRelease(releases, versionRange);
|
||||
// We only select the mod portal release if it is more recent than the local candidate
|
||||
if (release && (!candidate || release.integerVersion > candidate.integerVersion)) {
|
||||
candidate = release;
|
||||
}
|
||||
}
|
||||
|
||||
// Queue the dependencies of the new candidate
|
||||
if (candidate) {
|
||||
candidateReleases.set(mod.name, candidate);
|
||||
for (const dep of candidate.dependencies) {
|
||||
searchQueue.push(dep);
|
||||
}
|
||||
} else {
|
||||
candidateReleases.delete(mod.name);
|
||||
skipSearch.add(mod.name);
|
||||
}
|
||||
}
|
||||
|
||||
// Add the not found dependencies as errors
|
||||
for (const modName of dependencyRequirements.keys()) {
|
||||
if (!candidateReleases.has(modName) && !errors.has(modName)) {
|
||||
errors.set(modName, "notFound");
|
||||
}
|
||||
}
|
||||
|
||||
// Remove incompatible and unsatisfiable dependencies if they aren't required by others
|
||||
for (const [modName, error] of errors) {
|
||||
if (!dependencyRequirements.has(modName) && (error === "incompatible" || error === "unsatisfiable")) {
|
||||
errors.delete(modName);
|
||||
}
|
||||
}
|
||||
|
||||
return new lib.ModDependencyResolveRequest.Response(
|
||||
[...candidateReleases.values()], errors,
|
||||
return await this._controller.resolveModDependencies(
|
||||
request.mods, request.factorioVersion, request.checkForUpdates,
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -2,6 +2,7 @@ import type winston from "winston";
|
||||
import { BlockList, type AddressInfo, isIPv4, isIPv6 } from "net";
|
||||
import type { ControllerArgs } from "../controller.js";
|
||||
import type ControlConnection from "./ControlConnection.js";
|
||||
import type HostConnection from "./HostConnection.js";
|
||||
import express, { type Request, type Response, type NextFunction, type Application } from "express";
|
||||
import type { Static } from "@sinclair/typebox";
|
||||
import finalhandler from "finalhandler";
|
||||
@@ -11,7 +12,6 @@ import events from "events";
|
||||
import fs from "node:fs/promises";
|
||||
import http from "http";
|
||||
import https from "https";
|
||||
import jwt from "jsonwebtoken";
|
||||
import path from "path";
|
||||
import semver from "semver";
|
||||
import stream from "stream";
|
||||
@@ -28,7 +28,9 @@ import User from "./User.js";
|
||||
import UserRecord from "./UserRecord.js";
|
||||
import UserManager from "./UserManager.js";
|
||||
import WsServer from "./WsServer.js";
|
||||
import HostManager from "./HostManager.js";
|
||||
import HostRecord from "./HostRecord.js";
|
||||
import HostPairingManager from "./HostPairingManager.js";
|
||||
import { BaseControllerPlugin, ControllerHooks } from "./BaseControllerPlugin.js";
|
||||
import ControllerRouter from "./ControllerRouter.js";
|
||||
import InstanceManager from "./InstanceManager.js";
|
||||
@@ -46,6 +48,11 @@ const logSizeGauge = new Gauge(
|
||||
|
||||
type InstanceId = { instanceId: number };
|
||||
|
||||
const htmlEscapes: Record<string, string> = { "&": "&", "<": "<", ">": ">", "\"": """, "'": "'" };
|
||||
function escapeHtml(text: string) {
|
||||
return text.replace(/[&<>"']/g, char => htmlEscapes[char]);
|
||||
}
|
||||
|
||||
type ControllerDebugEvents = {
|
||||
"message": [ { direction: "in" | "out", content: string } ],
|
||||
};
|
||||
@@ -87,10 +94,14 @@ export default class Controller {
|
||||
|
||||
/** Event subscription controller */
|
||||
subscriptions: lib.SubscriptionController;
|
||||
/** Host manager for the cluster, also contains access to the host records */
|
||||
hosts: HostManager;
|
||||
/** User manager for the cluster, also contains access to the user records */
|
||||
users: UserManager;
|
||||
/** Instance manager for the cluster, also contains access to the user records */
|
||||
instances: InstanceManager;
|
||||
/** Pending requests from hosts to join the cluster */
|
||||
hostPairing: HostPairingManager;
|
||||
|
||||
// Possible states are new, starting, running, stopping, stopped
|
||||
private _state: string = "new";
|
||||
@@ -135,7 +146,7 @@ export default class Controller {
|
||||
const cachePath = path.join(this.config.get("controller.database_directory"), "latest-releases.json");
|
||||
try {
|
||||
const releases = await lib.fetchLatestReleases();
|
||||
await lib.safeOutputFile(cachePath, JSON.stringify(releases, null, "\t"));
|
||||
await lib.atomicOverwriteFile(cachePath, JSON.stringify(releases, null, "\t"));
|
||||
return releases;
|
||||
} catch (err: any) {
|
||||
logger.warn(`Failed to retrieve Factorio releases ${err.message}`);
|
||||
@@ -223,9 +234,17 @@ export default class Controller {
|
||||
await fs.mkdir(modsDirectory, { recursive: true });
|
||||
const modStore = await lib.ModStore.fromDirectory(modsDirectory);
|
||||
|
||||
await this.validateExports(modPacks, "static");
|
||||
|
||||
// Add default mod packs
|
||||
if (modPacks.size === 0) {
|
||||
modPacks.setMany(lib.ModPack.defaultModPacks);
|
||||
if (config.get("controller.default_mod_pack_id") === null) {
|
||||
const baseGame = lib.ModPack.defaultModPacks
|
||||
.filter(pack => pack.name.startsWith("Base Game "))
|
||||
.reduce((a, b) => (b.integerFactorioVersion > a.integerFactorioVersion ? b : a));
|
||||
config.set("controller.default_mod_pack_id", baseGame.id);
|
||||
}
|
||||
}
|
||||
|
||||
// Add default roles
|
||||
@@ -267,7 +286,7 @@ export default class Controller {
|
||||
public recoveryMode: boolean = false,
|
||||
public systems = new lib.SubscribableDatastore<lib.SystemInfo>(),
|
||||
/** Mapping of host id to host record */
|
||||
public hosts = new lib.SubscribableDatastore<HostRecord>(),
|
||||
hosts = new lib.SubscribableDatastore<HostRecord>(),
|
||||
/** Mapping of instance id to instance record */
|
||||
instances = new lib.SubscribableDatastore<InstanceRecord>(),
|
||||
/** Mapping of save id to save details */
|
||||
@@ -294,8 +313,10 @@ export default class Controller {
|
||||
this.trustedProxies = this.parseTrustedProxies();
|
||||
this.wsServer = new WsServer(this);
|
||||
|
||||
this.hosts = new HostManager(hosts, this);
|
||||
this.users = new UserManager(users, roles, config);
|
||||
this.instances = new InstanceManager(instances, this);
|
||||
this.hostPairing = new HostPairingManager(this);
|
||||
|
||||
this.modStore.on("change", mod => {
|
||||
this.modsUpdated([mod]);
|
||||
@@ -305,6 +326,7 @@ export default class Controller {
|
||||
this.subscriptions = new lib.SubscriptionController(config.get("controller.max_subscription_filters"));
|
||||
this.subscriptions.handle(lib.SystemInfoUpdateEvent, this.handleSystemInfoSubscription.bind(this));
|
||||
this.subscriptions.handle(lib.HostUpdatesEvent, this.handleHostSubscription.bind(this));
|
||||
this.subscriptions.handle(lib.HostPairingUpdatesEvent, this.handleHostPairingSubscription.bind(this));
|
||||
this.subscriptions.handle(lib.InstanceDetailsUpdatesEvent, this.handleInstanceDetailsSubscription.bind(this));
|
||||
this.subscriptions.handle(
|
||||
lib.InstanceSaveDetailsUpdatesEvent, this.handleInstanceSaveDetailsSubscription.bind(this)
|
||||
@@ -317,7 +339,8 @@ export default class Controller {
|
||||
|
||||
// Handle updates for datastores
|
||||
this.systems.on("update", this.systemsUpdated.bind(this));
|
||||
this.hosts.on("update", this.hostsUpdated.bind(this));
|
||||
this.hosts.records.on("update", this.hostsUpdated.bind(this));
|
||||
this.hostPairing.records.on("update", this.hostPairingRequestsUpdated.bind(this));
|
||||
this.instances.records.on("update", this.instanceUpdated.bind(this));
|
||||
this.saves.on("update", this.savesUpdated.bind(this));
|
||||
this.modPacks.on("update", this.modPacksUpdated.bind(this));
|
||||
@@ -420,7 +443,7 @@ export default class Controller {
|
||||
this.app.use(this.devServer.middlewares);
|
||||
}
|
||||
|
||||
if (!args.dev) {
|
||||
if (!this.devServer) {
|
||||
let manifestPath = path.join(import.meta.dirname, "..", "..", "web", "manifest.json");
|
||||
|
||||
let manifest = await Controller.loadJsonObject(manifestPath);
|
||||
@@ -462,7 +485,7 @@ export default class Controller {
|
||||
|
||||
// Only start listening for connections after all plugins have loaded
|
||||
if (httpPort) {
|
||||
this.httpServer = http.createServer(this.app);
|
||||
this.httpServer = http.createServer(routes.httpServerOptions, this.app);
|
||||
this.httpServerCloser = new HttpCloser(this.httpServer);
|
||||
await this.listen(this.httpServer, httpPort, bindAddress);
|
||||
logger.info(`Listening for HTTP on port ${(this.httpServer.address() as AddressInfo).port}`);
|
||||
@@ -481,6 +504,7 @@ export default class Controller {
|
||||
}
|
||||
|
||||
this.httpsServer = https.createServer({
|
||||
...routes.httpServerOptions,
|
||||
key: privateKey,
|
||||
cert: certificate,
|
||||
}, this.app);
|
||||
@@ -489,11 +513,15 @@ export default class Controller {
|
||||
logger.info(`Listening for HTTPS on port ${(this.httpsServer.address() as AddressInfo).port}`);
|
||||
}
|
||||
|
||||
this.onAutosaveIntervalChanged();
|
||||
this.onSystemMetricsIntervalChanged();
|
||||
this.hostPairing.start();
|
||||
|
||||
logger.info("Started controller");
|
||||
this.startedAtMs = Date.now();
|
||||
this.downloadRequiredMods().catch(
|
||||
err => logger.warn(`Unable to download mods required by plugins: ${err.message}`)
|
||||
);
|
||||
this.onAutosaveIntervalChanged();
|
||||
this.onSystemMetricsIntervalChanged();
|
||||
this._state = "running";
|
||||
}
|
||||
|
||||
@@ -527,14 +555,14 @@ export default class Controller {
|
||||
},
|
||||
plugins: [webUiVite.clusterioDevPlugins(pluginDirs)],
|
||||
});
|
||||
if (args.dev) {
|
||||
this.app.locals.webBundle = {
|
||||
main: this.devServer.config.plugins.find(p => p.name === "clusterio:app")!.api.entry,
|
||||
imports: Object.fromEntries(webUiVite.sharedModules.map(
|
||||
name => [name, webUiVite.devSharedUrl(name)]
|
||||
)),
|
||||
};
|
||||
}
|
||||
// Plugins served from source import the shared modules from the development server, the web
|
||||
// interface has to use the same copies, so it is served from source as well with --dev-plugin.
|
||||
this.app.locals.webBundle = {
|
||||
main: this.devServer.config.plugins.find(p => p.name === "clusterio:app")!.api.entry,
|
||||
imports: Object.fromEntries(webUiVite.sharedModules.map(
|
||||
name => [name, webUiVite.devSharedUrl(name)]
|
||||
)),
|
||||
};
|
||||
this.app.locals.devServer = this.devServer;
|
||||
}
|
||||
|
||||
@@ -582,6 +610,8 @@ export default class Controller {
|
||||
this.autosaveInterval = undefined;
|
||||
}
|
||||
|
||||
this.hostPairing.stop();
|
||||
|
||||
if (this.clusterLogIndex) {
|
||||
await this.clusterLogIndex.save();
|
||||
}
|
||||
@@ -648,6 +678,7 @@ export default class Controller {
|
||||
this.updateSystems.bind(this),
|
||||
systemMetricsIntervalSeconds * 1000
|
||||
);
|
||||
this.updateSystems();
|
||||
}
|
||||
}
|
||||
|
||||
@@ -673,6 +704,20 @@ export default class Controller {
|
||||
}
|
||||
}
|
||||
|
||||
/** Fetch system info from a host that just connected instead of waiting for the next interval */
|
||||
async updateHostSystem(hostConnection: HostConnection) {
|
||||
if (!(this.config.get("controller.system_metrics_interval") > 0)) {
|
||||
return;
|
||||
}
|
||||
try {
|
||||
this.systems.set(await hostConnection.send(new lib.SystemInfoRequest()));
|
||||
} catch (err: any) {
|
||||
logger.error(
|
||||
`Unexpected error updating system info of host ${hostConnection.id}:\n${err.stack ?? err.message}`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/** Plugins on the controller, including those installed or updated since it started */
|
||||
async listPlugins() {
|
||||
return await lib.listPluginDetails(
|
||||
@@ -785,7 +830,7 @@ export default class Controller {
|
||||
await Promise.all([
|
||||
this.config.save(),
|
||||
this.systems.save(),
|
||||
this.hosts.save(),
|
||||
this.hosts.records.save(),
|
||||
this.instances.records.save(),
|
||||
this.saves.save(),
|
||||
this.modPacks.save(),
|
||||
@@ -867,8 +912,43 @@ export default class Controller {
|
||||
});
|
||||
}
|
||||
|
||||
/** Remove export manifests that reference files missing from staticDirectory */
|
||||
static async validateExports(modPacks: lib.SubscribableDatastore<lib.ModPack>, staticDirectory: string) {
|
||||
const invalid: lib.ModPack[] = [];
|
||||
for (const modPack of modPacks.valuesMutable()) {
|
||||
if (!modPack.exportManifest) {
|
||||
continue;
|
||||
}
|
||||
const missing: string[] = [];
|
||||
for (const file of Object.values(modPack.exportManifest.assets)) {
|
||||
const valid = path.basename(file) === file
|
||||
&& await fs.stat(path.join(staticDirectory, file)).then(s => s.isFile(), () => false);
|
||||
if (!valid) {
|
||||
missing.push(file);
|
||||
}
|
||||
}
|
||||
if (missing.length) {
|
||||
Controller.dropExport(modPack, `missing ${missing.join(", ")}`);
|
||||
invalid.push(modPack);
|
||||
}
|
||||
}
|
||||
if (invalid.length) {
|
||||
modPacks.setMany(invalid);
|
||||
}
|
||||
}
|
||||
|
||||
/** Clear the export manifest of a mutable mod pack, caller must save it */
|
||||
static dropExport(modPack: lib.ModPack, reason: string) {
|
||||
logger.warn(`Removing export data of mod pack ${modPack.name} (id ${modPack.id}): ${reason}`);
|
||||
modPack.exportManifest = undefined;
|
||||
}
|
||||
|
||||
static migrateRoles(rawJson: unknown[]): Static<typeof lib.Role.jsonSchema>[] {
|
||||
const serialized = rawJson as Static<typeof lib.Role.jsonSchema>[];
|
||||
// migrate: host token permissions were removed with host pairing in 2.1
|
||||
const removedPermissions = new Set([
|
||||
"core.host.generate_token", "core.host.revoke_token", "core.host.create_config",
|
||||
]);
|
||||
return serialized.map(json => {
|
||||
json.permissions = json.permissions.map(permission => {
|
||||
// migrate: core.instance.save.list.subscribe was renamed in alpha 17
|
||||
@@ -876,7 +956,7 @@ export default class Controller {
|
||||
return "core.instance.save.subscribe";
|
||||
}
|
||||
return permission;
|
||||
});
|
||||
}).filter(permission => !removedPermissions.has(permission));
|
||||
return lib.Role.pluginMigrations.reduce(json);
|
||||
});
|
||||
}
|
||||
@@ -971,6 +1051,7 @@ export default class Controller {
|
||||
express.static(path.join(import.meta.dirname, "..", "..", "web", "static"), staticOptions)
|
||||
);
|
||||
app.use("/static", express.static("static", staticOptions)); // Used for data export files
|
||||
app.use("/static", routes.missingExportAsset);
|
||||
|
||||
// Add API routes
|
||||
routes.addRouteHandlers(app);
|
||||
@@ -1002,21 +1083,25 @@ export default class Controller {
|
||||
return systems.length ? new lib.SystemInfoUpdateEvent(systems) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate access token for host
|
||||
*
|
||||
* @returns access token for host
|
||||
* @param hostId - ID of host to generate a token for.
|
||||
*/
|
||||
generateHostToken(hostId: number): string {
|
||||
return jwt.sign({ aud: "host", host: hostId }, this.authSecret);
|
||||
}
|
||||
|
||||
hostsUpdated(hosts: HostRecord[]) {
|
||||
let updates = hosts.map(host => host.toHostDetails());
|
||||
this.subscriptions.broadcast(new lib.HostUpdatesEvent(updates));
|
||||
}
|
||||
|
||||
hostPairingRequestsUpdated(requests: lib.HostPairingDetails[]) {
|
||||
this.subscriptions.broadcast(new lib.HostPairingUpdatesEvent(requests));
|
||||
}
|
||||
|
||||
async handleHostPairingSubscription(request: lib.SubscriptionRequest) {
|
||||
if (request.action === "unsubscribe") {
|
||||
return null;
|
||||
}
|
||||
const requests = [...this.hostPairing.records.values()].filter(
|
||||
pairing => pairing.updatedAtMs > request.lastRequestTimeMs,
|
||||
);
|
||||
return requests.length ? new lib.HostPairingUpdatesEvent(requests) : null;
|
||||
}
|
||||
|
||||
async handleHostSubscription(request: lib.SubscriptionRequest) {
|
||||
if (request.action === "unsubscribe") {
|
||||
return null;
|
||||
@@ -1092,6 +1177,265 @@ export default class Controller {
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Download mods from the Factorio mod portal to the mod store
|
||||
*
|
||||
* Mods already in the mod store are skipped.
|
||||
*
|
||||
* @throws {lib.ConflictError} if the Factorio credentials are not configured.
|
||||
*/
|
||||
async downloadModsFromPortal(mods: lib.ModNameVersionPair[], factorioVersion: lib.MajorMinorVersion) {
|
||||
const toDownload = this.modStore.filterInstalled(mods, false);
|
||||
|
||||
if (toDownload.length > 0) {
|
||||
// Get Factorio credentials from config
|
||||
const username = this.config.get("controller.factorio_username");
|
||||
const token = this.config.get("controller.factorio_token");
|
||||
|
||||
if (!username || username === "" || !token || token === "") {
|
||||
throw new lib.ConflictError("Factorio credentials (username, token) not configured on the controller.");
|
||||
}
|
||||
|
||||
try {
|
||||
logger.info(`Downloading ${toDownload.length} mods for Factorio ${factorioVersion} from portal.`);
|
||||
await this.modStore.downloadMods(toDownload, username, token, factorioVersion);
|
||||
|
||||
} catch (error: any) {
|
||||
logger.error(`Error downloading mods from portal: ${error.message}`);
|
||||
const errorMessage = "Mod portal download failed";
|
||||
if (error.message.includes("401") || error.message.includes("Unauthorized")) {
|
||||
throw new lib.ConflictError(
|
||||
`${errorMessage}: Authentication failed. Check Factorio username/token in controller config.`
|
||||
);
|
||||
}
|
||||
if (error.message.includes("404") || error.message.includes("Not Found")) {
|
||||
throw new lib.NotFoundError(`${errorMessage}: Mod version not found on the portal.`);
|
||||
}
|
||||
throw new lib.InternalServerError(`${errorMessage}: ${error.message}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve mods and their dependencies against the mod store and the Factorio mod portal
|
||||
*/
|
||||
// eslint-disable-next-line complexity
|
||||
async resolveModDependencies(
|
||||
mods: lib.ModDependency[],
|
||||
factorioVersion: lib.MajorMinorVersion,
|
||||
checkForUpdates = false,
|
||||
) {
|
||||
const searchQueue = [...mods];
|
||||
const localInfos = [...this.modStore.mods()];
|
||||
|
||||
const builtInModNames = lib.ModPack.getBuiltinModNames(factorioVersion);
|
||||
const skipSearch = new Set(builtInModNames);
|
||||
|
||||
type ModPortalModType = InstanceType<typeof lib.ModPortalGetAllRequest.Response>["mods"][number];
|
||||
type ModPortalReleaseType = NonNullable<ModPortalModType["releases"]>[number];
|
||||
const dependencyRequirements = new Map<string, lib.ModVersionRange>();
|
||||
const recommendedRequirements = new Map<string, lib.ModVersionRange>();
|
||||
const optionalRequirements = new Map<string, lib.ModVersionRange>();
|
||||
const candidateReleases = new Map<string, lib.ModInfo>();
|
||||
const errors = new Map<string, lib.ModDependencyResolveErrors>();
|
||||
|
||||
const _modPortalReleases = new Map<string, ModPortalModType | null>();
|
||||
async function fetchModReleases(modName: string) {
|
||||
let releases = _modPortalReleases.get(modName);
|
||||
if (releases === undefined) {
|
||||
try {
|
||||
releases = await lib.ModStore.fetchModReleases(modName);
|
||||
} catch (error: any) {
|
||||
if (!error.message.includes("404") && !error.message.includes("Not Found")) {
|
||||
logger.error(`Error fetching mod from portal: ${error.message}`);
|
||||
throw new lib.InternalServerError(`Dependency resolution failed: ${error.message}`);
|
||||
} else {
|
||||
releases = null;
|
||||
}
|
||||
}
|
||||
}
|
||||
_modPortalReleases.set(modName, releases);
|
||||
return releases;
|
||||
}
|
||||
|
||||
function selectModRelease(releases: ModPortalModType | null, versionRange: lib.ModVersionRange) {
|
||||
if (!releases || !releases.releases) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Select the latest matching version for the mod pack's Factorio version
|
||||
const release = releases.releases
|
||||
.filter(info => (
|
||||
versionRange.testVersion(info.version)
|
||||
&& lib.normaliseMajorMinorVersion(
|
||||
lib.normaliseSourceVersion(info.info_json.factorio_version)
|
||||
) === factorioVersion
|
||||
))
|
||||
.reduce<ModPortalReleaseType | undefined>((max, cur) => (
|
||||
max && lib.integerSourceVersion(max.version) > lib.integerSourceVersion(cur.version) ? max : cur
|
||||
), undefined);
|
||||
|
||||
if (!release) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Create the mod info class from the selected
|
||||
try {
|
||||
return lib.ModInfo.fromJSON({
|
||||
...release.info_json, // includes dependencies
|
||||
sha1: release.sha1,
|
||||
version: release.version,
|
||||
name: releases.name,
|
||||
author: releases.owner,
|
||||
title: releases.title,
|
||||
});
|
||||
} catch {
|
||||
// Can error if there are invalid dependencies
|
||||
errors.set(releases.name, "invalidDependency");
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
while (searchQueue.length > 0) {
|
||||
// Dequeue the next mod, skip if incompatible
|
||||
const mod = searchQueue.shift()!;
|
||||
if (mod.incompatible) {
|
||||
errors.set(mod.name, "incompatible");
|
||||
continue;
|
||||
}
|
||||
|
||||
// Get the current version range (dependencies can be promoted to a stricter requirement)
|
||||
const versionRange =
|
||||
dependencyRequirements.get(mod.name)
|
||||
?? recommendedRequirements.get(mod.name)
|
||||
?? optionalRequirements.get(mod.name)
|
||||
?? new lib.ModVersionRange();
|
||||
|
||||
if (mod.required) {
|
||||
// Add to required, remove from recommended and optional
|
||||
dependencyRequirements.set(mod.name, versionRange);
|
||||
recommendedRequirements.delete(mod.name);
|
||||
optionalRequirements.delete(mod.name);
|
||||
|
||||
} else if (mod.recommended) {
|
||||
// If not required, add to recommended and remove from optional
|
||||
if (!dependencyRequirements.has(mod.name)) {
|
||||
recommendedRequirements.set(mod.name, versionRange);
|
||||
optionalRequirements.delete(mod.name);
|
||||
}
|
||||
|
||||
} else if (
|
||||
!dependencyRequirements.has(mod.name)
|
||||
&& !recommendedRequirements.has(mod.name)
|
||||
) {
|
||||
// If not required or recommended, add to optional
|
||||
optionalRequirements.set(mod.name, versionRange);
|
||||
}
|
||||
|
||||
// Update the version range if needed
|
||||
if (mod.version) {
|
||||
versionRange.combineVersion(mod.version);
|
||||
if (!versionRange.valid) {
|
||||
candidateReleases.delete(mod.name);
|
||||
errors.set(mod.name, "unsatisfiable");
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
// Do not add dependencies for errors, skips, optionals, or valid candidates
|
||||
const existingCandidate = candidateReleases.get(mod.name);
|
||||
if (errors.has(mod.name) || skipSearch.has(mod.name) || optionalRequirements.has(mod.name) || (
|
||||
existingCandidate && versionRange.testVersion(existingCandidate.version)
|
||||
)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Check if a local version fits the requirements
|
||||
let candidate = localInfos
|
||||
.filter(info => (
|
||||
info.name === mod.name
|
||||
&& info.factorioVersion === factorioVersion
|
||||
&& versionRange.testVersion(info.version)
|
||||
))
|
||||
.reduce<lib.ModInfo | undefined>((max, cur) => (
|
||||
max && max.integerVersion > cur.integerVersion ? max : cur
|
||||
), undefined);
|
||||
|
||||
// Check if a mod poral version fits the requirements
|
||||
if (!candidate || checkForUpdates) {
|
||||
const releases = await fetchModReleases(mod.name);
|
||||
const release = selectModRelease(releases, versionRange);
|
||||
// We only select the mod portal release if it is more recent than the local candidate
|
||||
if (release && (!candidate || release.integerVersion > candidate.integerVersion)) {
|
||||
candidate = release;
|
||||
}
|
||||
}
|
||||
|
||||
// Queue the dependencies of the new candidate
|
||||
if (candidate) {
|
||||
candidateReleases.set(mod.name, candidate);
|
||||
for (const dep of candidate.dependencies) {
|
||||
searchQueue.push(dep);
|
||||
}
|
||||
} else {
|
||||
candidateReleases.delete(mod.name);
|
||||
skipSearch.add(mod.name);
|
||||
}
|
||||
}
|
||||
|
||||
// Add the not found dependencies as errors
|
||||
for (const modName of dependencyRequirements.keys()) {
|
||||
if (!candidateReleases.has(modName) && !errors.has(modName)) {
|
||||
errors.set(modName, "notFound");
|
||||
}
|
||||
}
|
||||
|
||||
// Remove incompatible and unsatisfiable dependencies if they aren't required by others
|
||||
for (const [modName, error] of errors) {
|
||||
if (!dependencyRequirements.has(modName) && (error === "incompatible" || error === "unsatisfiable")) {
|
||||
errors.delete(modName);
|
||||
}
|
||||
}
|
||||
|
||||
return new lib.ModDependencyResolveRequest.Response(
|
||||
[...candidateReleases.values()], errors,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Download the mods required by plugins that are missing from the mod store
|
||||
*
|
||||
* Resolves for the Factorio version of the default mod pack. Dependencies
|
||||
* of the required mods are downloaded too.
|
||||
*/
|
||||
async downloadRequiredMods() {
|
||||
const required = this.pluginInfos.flatMap(pluginInfo => lib.pluginRequiredMods(pluginInfo));
|
||||
const modPackId = this.config.get("controller.default_mod_pack_id");
|
||||
const modPack = modPackId !== null ? this.modPacks.get(modPackId) : undefined;
|
||||
if (!required.length || !modPack) {
|
||||
return;
|
||||
}
|
||||
|
||||
const factorioVersion = lib.normaliseMajorMinorVersion(modPack.factorioVersion);
|
||||
const { dependencies, errors } = await this.resolveModDependencies(required, factorioVersion);
|
||||
const builtInMods = new Set(lib.ModPack.getBuiltinModNames(factorioVersion));
|
||||
for (const [name, error] of errors) {
|
||||
if (!builtInMods.has(name)) {
|
||||
logger.warn(`Unable to resolve mod ${name} required by plugins: ${error}`);
|
||||
}
|
||||
}
|
||||
const toDownload = this.modStore.filterInstalled(dependencies.map(
|
||||
info => ({ name: info.name, version: new lib.ModVersionEquality("=", info.normalisedVersion) })
|
||||
), false);
|
||||
if (!toDownload.length) {
|
||||
return;
|
||||
}
|
||||
|
||||
const names = toDownload.map(mod => `${mod.name} ${mod.version.version}`).join(", ");
|
||||
logger.info(`Downloading mods required by plugins: ${names}`);
|
||||
await this.downloadModsFromPortal(toDownload, factorioVersion);
|
||||
}
|
||||
|
||||
modPacksUpdated(modPacks: lib.ModPack[]) {
|
||||
this.subscriptions.broadcast(new lib.ModPackUpdatesEvent(modPacks));
|
||||
this.hooks.modPacksUpdated.invoke(modPacks);
|
||||
@@ -1241,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");
|
||||
@@ -1264,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);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1381,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)
|
||||
|
||||
@@ -34,26 +34,24 @@ export default class HostConnection extends BaseConnection {
|
||||
|
||||
this.plugins = new Map(Object.entries(registerData.plugins));
|
||||
|
||||
const previousHostInfo = this._controller.hosts.get(registerData.id);
|
||||
this.info = new HostRecord(
|
||||
registerData.id,
|
||||
previousHostInfo?.name ?? "",
|
||||
registerData.version,
|
||||
this.plugins,
|
||||
true,
|
||||
remoteAddress,
|
||||
previousHostInfo?.publicAddress,
|
||||
previousHostInfo?.tokenValidAfter,
|
||||
0,
|
||||
false,
|
||||
);
|
||||
this._controller.hosts.set(this.info);
|
||||
// Hosts are only created by approving them, WsServer rejects hosts without a record.
|
||||
const record = this._controller.hosts.getMutable(registerData.id);
|
||||
if (!record) {
|
||||
throw new Error(`Host ${registerData.id} is not registered`);
|
||||
}
|
||||
record.version = registerData.version;
|
||||
record.plugins = this.plugins;
|
||||
record.connected = true;
|
||||
record.remoteAddress = remoteAddress;
|
||||
this.info = record;
|
||||
this._controller.hosts.records.set(this.info);
|
||||
|
||||
this._checkPluginVersions();
|
||||
|
||||
for (let event of ["connect", "drop", "resume", "close"] as const) {
|
||||
this.connector.on(event, () => this._controller.hooks.hostConnectionEvent.invoke(this, event));
|
||||
}
|
||||
this.connector.on("connect", () => { this._controller.updateHostSystem(this); });
|
||||
|
||||
this.connector.on("close", () => {
|
||||
// Update status to unknown for instances on this host.
|
||||
@@ -71,7 +69,7 @@ export default class HostConnection extends BaseConnection {
|
||||
this._controller.instances.records.setMany(instances);
|
||||
|
||||
this.info.connected = false;
|
||||
this._controller.hosts.set(this.info);
|
||||
this.saveRecord();
|
||||
});
|
||||
|
||||
this.handle(lib.GetFactorioCredentialsRequest, this.handleGetFactorioCredentialsRequest.bind(this));
|
||||
@@ -175,10 +173,17 @@ export default class HostConnection extends BaseConnection {
|
||||
return {};
|
||||
}
|
||||
|
||||
/** Store changes to the host record, unless the host was revoked */
|
||||
saveRecord() {
|
||||
if (this._controller.hosts.getMutable(this.id) === this.info) {
|
||||
this._controller.hosts.records.set(this.info);
|
||||
}
|
||||
}
|
||||
|
||||
async handleHostInfoUpdateEvent(event: lib.HostInfoUpdateEvent) {
|
||||
this.info.name = event.update.name;
|
||||
this.info.publicAddress = event.update.publicAddress;
|
||||
this._controller.hosts.set(this.info);
|
||||
this.saveRecord();
|
||||
}
|
||||
|
||||
async handleInstanceStatusChangedEvent(request: lib.InstanceStatusChangedEvent) {
|
||||
|
||||
@@ -0,0 +1,149 @@
|
||||
import crypto from "node:crypto";
|
||||
import jwt from "jsonwebtoken";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
|
||||
import type Controller from "./Controller.js";
|
||||
import HostRecord from "./HostRecord.js";
|
||||
|
||||
/**
|
||||
* Access layer for hosts on the controller.
|
||||
*
|
||||
* @alias module:controller/src/HostManager
|
||||
*/
|
||||
export default class HostManager {
|
||||
constructor(
|
||||
public readonly records: lib.SubscribableDatastore<HostRecord>,
|
||||
private readonly _controller: Controller,
|
||||
) { }
|
||||
|
||||
/* ------------------------------------------------------------------------- */
|
||||
/* Basic Accessors */
|
||||
/* ------------------------------------------------------------------------- */
|
||||
|
||||
has(id: HostRecord["id"]): boolean {
|
||||
return this.records.has(id);
|
||||
}
|
||||
|
||||
getMutable(id: HostRecord["id"]): HostRecord | undefined {
|
||||
return this.records.getMutable(id);
|
||||
}
|
||||
|
||||
get(id: HostRecord["id"]): Readonly<HostRecord> | undefined {
|
||||
return this.records.get(id);
|
||||
}
|
||||
|
||||
valuesMutable(): IterableIterator<HostRecord> {
|
||||
return this.records.values();
|
||||
}
|
||||
|
||||
values(): IterableIterator<Readonly<HostRecord>> {
|
||||
return this.valuesMutable();
|
||||
}
|
||||
|
||||
/**
|
||||
* Get host by ID for a request.
|
||||
*
|
||||
* @param hostId - ID of host to get.
|
||||
* @returns The host record.
|
||||
* @throws {module:lib.NotFoundError} if the host does not exist.
|
||||
*/
|
||||
getForRequest(hostId: number): HostRecord {
|
||||
const host = this.records.getMutable(hostId);
|
||||
if (!host) {
|
||||
throw new lib.NotFoundError(`Unknown host id (${hostId})`);
|
||||
}
|
||||
return host;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------------- */
|
||||
/* Lifecycle */
|
||||
/* ------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Create a host record with a new random id
|
||||
*
|
||||
* @param name - Name of the host.
|
||||
* @returns the created host record.
|
||||
*/
|
||||
createHost(name: string): HostRecord {
|
||||
let hostId;
|
||||
do {
|
||||
hostId = crypto.randomInt(1, 2 ** 31);
|
||||
} while (this.records.has(hostId));
|
||||
|
||||
const host = new HostRecord(
|
||||
hostId, name, "", new Map(), false, "", "", Math.floor(Date.now() / 1000),
|
||||
);
|
||||
this.records.set(host);
|
||||
return host;
|
||||
}
|
||||
|
||||
/**
|
||||
* Delete a host, disconnect it and unassign its instances
|
||||
*
|
||||
* @param hostId - ID of host to revoke.
|
||||
* @param revokedBy - Name of the user revoking it, for logging.
|
||||
*/
|
||||
async revokeHost(hostId: number, revokedBy: string) {
|
||||
const host = this.getForRequest(hostId);
|
||||
this.records.delete(host);
|
||||
this._controller.deleteNote("host", hostId, revokedBy);
|
||||
const system = this._controller.systems.getMutable(hostId);
|
||||
if (system) {
|
||||
this._controller.systems.delete(system);
|
||||
}
|
||||
|
||||
// Disconnected first so unassigning the instances does not depend on the host responding.
|
||||
const hostConnection = this._controller.wsServer.hostConnections.get(hostId);
|
||||
if (hostConnection) {
|
||||
hostConnection.connector.terminate();
|
||||
}
|
||||
const assigned = [...this._controller.instances.values()].filter(
|
||||
instance => instance.config.get("instance.assigned_host") === hostId
|
||||
);
|
||||
for (const instance of assigned) {
|
||||
await this._controller.instances.unassignInstance(instance.id);
|
||||
}
|
||||
logger.audit(`User ${revokedBy} revoked host ${host.name} (${host.id})`);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------------- */
|
||||
/* Helpers */
|
||||
/* ------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Sign access token for the given host
|
||||
*
|
||||
* @param hostId - ID of host to sign token for.
|
||||
* @returns JWT access token for the host.
|
||||
*/
|
||||
signHostToken(hostId: number): string {
|
||||
return jwt.sign({ aud: "host", host: hostId }, this._controller.authSecret);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check a host token
|
||||
*
|
||||
* @param token - Host token to check.
|
||||
* @returns the host the token was issued to.
|
||||
* @throws if the token is invalid, its host is not registered or it was issued before tokenValidAfter.
|
||||
*/
|
||||
verifyHostToken(token: string): HostRecord {
|
||||
// migrate: allow pre-rename tokens issued to hosts before alpha-14
|
||||
const payload = jwt.verify(token, this._controller.authSecret, { audience: ["host", "slave"] });
|
||||
if (typeof payload === "string") {
|
||||
throw new Error("unexpected JsonWebToken type");
|
||||
}
|
||||
const hostId = payload.host !== undefined ? payload.host : payload.slave;
|
||||
const host = this.records.getMutable(hostId);
|
||||
if (!host) {
|
||||
throw new Error("host is not registered, start the host again to request to join the cluster");
|
||||
}
|
||||
if (!payload.iat || payload.iat < host.tokenValidAfter) {
|
||||
throw new Error("invalid token");
|
||||
}
|
||||
return host;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,299 @@
|
||||
import type Controller from "./Controller.js";
|
||||
|
||||
import crypto from "crypto";
|
||||
import net from "net";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
|
||||
/** Symbols used in pairing codes, avoids 0/O and 1/I/L */
|
||||
const codeAlphabet = "23456789ABCDEFGHJKMNPQRSTUVWXYZ";
|
||||
const codeLength = 6;
|
||||
|
||||
/** Time a request is kept after the last poll from the host */
|
||||
export const pollTimeoutMs = 30e3;
|
||||
/** Maximum number of pending requests from one address */
|
||||
export const maxPendingPerAddress = 3;
|
||||
/** Maximum length of a host name */
|
||||
export const maxNameLength = 100;
|
||||
/** Control and bidirectional override characters refused in host names */
|
||||
const nameControlCharacters = /[\p{Cc}\u202a-\u202e\u2066-\u2069]/u;
|
||||
|
||||
/** Result of an approved request, sent to the host */
|
||||
export interface HostPairingResult {
|
||||
hostId: number,
|
||||
token: string,
|
||||
name: string,
|
||||
}
|
||||
|
||||
/** Error with an HTTP status code to respond to the host with */
|
||||
export class HostPairingError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
public status: number,
|
||||
/** Seconds to wait before trying again, for status 429 */
|
||||
public retryAfter?: number,
|
||||
) {
|
||||
super(message);
|
||||
}
|
||||
}
|
||||
|
||||
type PairingRequest = {
|
||||
/** Secret the host polls with, never shown to users */
|
||||
secret: string,
|
||||
details: lib.HostPairingDetails,
|
||||
/** Address with IPv6 addresses grouped by /64, used for limits */
|
||||
addressKey: string,
|
||||
lastPollMs: number,
|
||||
} & (
|
||||
{ state: "pending" | "rejected" } | { state: "approved", result: HostPairingResult }
|
||||
);
|
||||
|
||||
/**
|
||||
* Strips the IPv4 mapped prefix and groups IPv6 addresses by their /64
|
||||
*
|
||||
* @param address - Address to make a key for
|
||||
* @returns key used to count requests from an address.
|
||||
*/
|
||||
export function addressKey(address: string) {
|
||||
if (address.startsWith("::ffff:") && net.isIPv4(address.slice(7))) {
|
||||
return address.slice(7);
|
||||
}
|
||||
if (!net.isIPv6(address)) {
|
||||
return address;
|
||||
}
|
||||
const [head, tail = ""] = address.split("::");
|
||||
const headParts = head ? head.split(":") : [];
|
||||
const tailParts = tail ? tail.split(":") : [];
|
||||
const missing = 8 - headParts.length - tailParts.length;
|
||||
const parts = address.includes("::")
|
||||
? [...headParts, ...new Array(missing).fill("0"), ...tailParts]
|
||||
: headParts;
|
||||
return `${parts.slice(0, 4).map(part => part.toLowerCase().replace(/^0+(?=.)/, "")).join(":")}::/64`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Normalise a pairing code typed by a user
|
||||
*
|
||||
* @param code - Code as typed, may contain dashes and lower case letters.
|
||||
* @returns code formatted as shown by the host.
|
||||
*/
|
||||
export function normaliseCode(code: string) {
|
||||
const plain = code.toUpperCase().replace(/[^0-9A-Z]/g, "");
|
||||
return `${plain.slice(0, 3)}-${plain.slice(3)}`;
|
||||
}
|
||||
|
||||
function generateCode() {
|
||||
let code = "";
|
||||
for (let i = 0; i < codeLength; i++) {
|
||||
code += codeAlphabet[crypto.randomInt(codeAlphabet.length)];
|
||||
}
|
||||
return normaliseCode(code);
|
||||
}
|
||||
|
||||
/**
|
||||
* Keeps track of requests from hosts to join the cluster
|
||||
*
|
||||
* Requests only live in memory, and only while the host keeps polling
|
||||
* for the result.
|
||||
*/
|
||||
export default class HostPairingManager {
|
||||
/** Pending requests by code, broadcast to subscribed control links */
|
||||
records = new lib.SubscribableDatastore<lib.HostPairingDetails>();
|
||||
private _bySecret = new Map<string, PairingRequest>();
|
||||
private _byCode = new Map<string, PairingRequest>();
|
||||
private _pruneInterval?: ReturnType<typeof setInterval>;
|
||||
|
||||
constructor(
|
||||
private _controller: Controller,
|
||||
) { }
|
||||
|
||||
start() {
|
||||
this._pruneInterval = setInterval(() => this.prune(), 5e3);
|
||||
this._pruneInterval.unref();
|
||||
}
|
||||
|
||||
stop() {
|
||||
clearInterval(this._pruneInterval);
|
||||
this._pruneInterval = undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Check and trim a host name given by a host or a user
|
||||
*
|
||||
* @param name - Name to check.
|
||||
* @returns the trimmed name.
|
||||
*/
|
||||
static validateName(name: unknown) {
|
||||
if (typeof name !== "string" || !name.trim()) {
|
||||
throw new HostPairingError("Host name is required", 400);
|
||||
}
|
||||
const trimmed = name.trim();
|
||||
if (trimmed.length > maxNameLength) {
|
||||
throw new HostPairingError(`Host name must be at most ${maxNameLength} characters`, 400);
|
||||
}
|
||||
// Names come from unauthenticated requests and are printed to terminals and logs.
|
||||
if (nameControlCharacters.test(trimmed)) {
|
||||
throw new HostPairingError("Host name may not contain control characters", 400);
|
||||
}
|
||||
return trimmed;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a pending request
|
||||
*
|
||||
* @param name - Name the host asked for.
|
||||
* @param version - Version of the host.
|
||||
* @param remoteAddress - Address the request came from.
|
||||
* @returns the secret to poll with and the code to show the user.
|
||||
*/
|
||||
create(name: string, version: string, remoteAddress: string) {
|
||||
this.prune();
|
||||
const key = addressKey(remoteAddress);
|
||||
const now = Date.now();
|
||||
const pendingFromAddress = [...this._bySecret.values()].filter(
|
||||
request => request.addressKey === key && request.state === "pending"
|
||||
).length;
|
||||
if (pendingFromAddress >= maxPendingPerAddress) {
|
||||
throw new HostPairingError("Too many pending requests from this address", 429, 30);
|
||||
}
|
||||
const maxPending = this._controller.config.get("controller.host_pairing_max_pending");
|
||||
if (maxPending && this.records.size >= maxPending) {
|
||||
throw new HostPairingError("Too many pending requests", 429, 30);
|
||||
}
|
||||
|
||||
let code;
|
||||
do {
|
||||
code = generateCode();
|
||||
} while (this._byCode.has(code));
|
||||
|
||||
const request: PairingRequest = {
|
||||
secret: crypto.randomBytes(32).toString("base64url"),
|
||||
details: new lib.HostPairingDetails(code, name, remoteAddress, version, now),
|
||||
addressKey: key,
|
||||
lastPollMs: now,
|
||||
state: "pending",
|
||||
};
|
||||
this._bySecret.set(request.secret, request);
|
||||
this._byCode.set(code, request);
|
||||
this.records.set(request.details);
|
||||
logger.verbose(`Host pairing request ${code} for "${name}" from ${remoteAddress}`);
|
||||
return { requestId: request.secret, code };
|
||||
}
|
||||
|
||||
/**
|
||||
* Poll for the result of a request
|
||||
*
|
||||
* @param secret - Request id returned when the request was created.
|
||||
* @returns the result if the request was approved, or null if still pending.
|
||||
*/
|
||||
poll(secret: string): HostPairingResult | null {
|
||||
this.prune();
|
||||
const request = this._bySecret.get(secret);
|
||||
if (!request) {
|
||||
throw new HostPairingError("Request not found", 404);
|
||||
}
|
||||
request.lastPollMs = Date.now();
|
||||
if (request.state === "approved") {
|
||||
this._remove(request);
|
||||
return request.result;
|
||||
}
|
||||
if (request.state === "rejected") {
|
||||
this._remove(request);
|
||||
throw new HostPairingError("Request was rejected", 403);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Cancel a pending request
|
||||
*
|
||||
* @param secret - Request id returned when the request was created.
|
||||
*/
|
||||
cancel(secret: string) {
|
||||
const request = this._bySecret.get(secret);
|
||||
if (request && request.state === "pending") {
|
||||
logger.verbose(`Host pairing request ${request.details.code} cancelled by the host`);
|
||||
this._remove(request);
|
||||
}
|
||||
}
|
||||
|
||||
private _pending(code: string) {
|
||||
this.prune();
|
||||
const request = this._byCode.get(normaliseCode(code));
|
||||
if (!request || request.state !== "pending") {
|
||||
throw new lib.NotFoundError(`No pending host request with code ${code}`);
|
||||
}
|
||||
return request;
|
||||
}
|
||||
|
||||
/**
|
||||
* Approve a pending request, creating the host
|
||||
*
|
||||
* @param code - Code of the request.
|
||||
* @param name - Name to give the host, defaults to the requested name.
|
||||
* @param approvedBy - Name of the user approving it, for logging.
|
||||
* @returns the id of the new host.
|
||||
*/
|
||||
approve(code: string, name: string | undefined, approvedBy: string) {
|
||||
const request = this._pending(code);
|
||||
let hostName;
|
||||
try {
|
||||
hostName = name === undefined ? request.details.name : HostPairingManager.validateName(name);
|
||||
} catch (err: any) {
|
||||
throw new lib.ValidationError(err.message);
|
||||
}
|
||||
|
||||
const host = this._controller.hosts.createHost(hostName);
|
||||
const result = { hostId: host.id, token: this._controller.hosts.signHostToken(host.id), name: host.name };
|
||||
Object.assign(request, { state: "approved", result });
|
||||
this.records.delete(request.details);
|
||||
logger.audit(
|
||||
`User ${approvedBy} approved host ${result.name} (${result.hostId}) with code ` +
|
||||
`${request.details.code} from ${request.details.remoteAddress}`
|
||||
);
|
||||
return result.hostId;
|
||||
}
|
||||
|
||||
/**
|
||||
* Reject a pending request
|
||||
*
|
||||
* @param code - Code of the request.
|
||||
* @param rejectedBy - Name of the user rejecting it, for logging.
|
||||
*/
|
||||
reject(code: string, rejectedBy: string) {
|
||||
const request = this._pending(code);
|
||||
request.state = "rejected";
|
||||
this.records.delete(request.details);
|
||||
logger.audit(
|
||||
`User ${rejectedBy} rejected host ${request.details.name} with code ` +
|
||||
`${request.details.code} from ${request.details.remoteAddress}`
|
||||
);
|
||||
}
|
||||
|
||||
private _remove(request: PairingRequest) {
|
||||
this._bySecret.delete(request.secret);
|
||||
this._byCode.delete(request.details.code);
|
||||
this.records.delete(request.details);
|
||||
}
|
||||
|
||||
/** Remove requests the host stopped polling for or that waited too long */
|
||||
prune() {
|
||||
const now = Date.now();
|
||||
const timeoutMs = this._controller.config.get("controller.host_pairing_timeout") * 1000;
|
||||
for (const request of this._bySecret.values()) {
|
||||
const timedOut = request.state === "pending" && timeoutMs > 0
|
||||
&& now - request.details.createdAtMs > timeoutMs;
|
||||
if (!timedOut && now - request.lastPollMs <= pollTimeoutMs) {
|
||||
continue;
|
||||
}
|
||||
if (request.state === "approved") {
|
||||
logger.warn(
|
||||
`Approved host ${request.result.name} (${request.result.hostId}) was never picked up ` +
|
||||
"by the host, revoke it on the hosts page if it is not needed"
|
||||
);
|
||||
}
|
||||
this._remove(request);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,9 +1,14 @@
|
||||
import { isDeepStrictEqual } from "node:util";
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
|
||||
import type Controller from "./Controller.js";
|
||||
import type HostConnection from "./HostConnection.js";
|
||||
import InstanceRecord from "./InstanceRecord.js";
|
||||
|
||||
type InheritedFields = lib.InstanceConfigFields["instance.inherited_fields"];
|
||||
type InheritableField = keyof lib.InstanceConfigFields & string;
|
||||
|
||||
export default class InstanceManager {
|
||||
private static readonly DefaultFactorioSettings = {
|
||||
tags: ["clusterio"],
|
||||
@@ -24,6 +29,9 @@ export default class InstanceManager {
|
||||
non_blocking_saving: false,
|
||||
} as const;
|
||||
|
||||
/** Non-zero while template values are being copied into inheriting instances */
|
||||
private _inheriting = 0;
|
||||
|
||||
constructor(
|
||||
public readonly records: lib.SubscribableDatastore<InstanceRecord>,
|
||||
private readonly _controller: Controller,
|
||||
@@ -106,11 +114,271 @@ export default class InstanceManager {
|
||||
*/
|
||||
addInstanceHooks(instance: InstanceRecord): void {
|
||||
instance.config.on("fieldChanged", (field: string, curr: unknown, prev: unknown) => {
|
||||
if (field === "instance.template_id") {
|
||||
this._linkMatchingFields(instance);
|
||||
} else if (!this._inheriting && instance.config.isInherited(field)) {
|
||||
this._unlinkEditedField(instance, field, curr, prev);
|
||||
}
|
||||
this.records.set(instance);
|
||||
this._notifyConfigFieldChanged(instance, field, curr, prev);
|
||||
this._updateInheritors(instance, field, curr);
|
||||
});
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------------- */
|
||||
/* Inheritance */
|
||||
/* ------------------------------------------------------------------------- */
|
||||
|
||||
/**
|
||||
* Get the instances that inherit directly from the given template.
|
||||
*
|
||||
* @param templateId - ID of the template.
|
||||
* @returns Instances with `instance.template_id` set to templateId.
|
||||
*/
|
||||
inheritorsOf(templateId: number): InstanceRecord[] {
|
||||
return [...this.records.values()].filter(
|
||||
instance => instance.config.get("instance.template_id") === templateId
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check that new values for `instance.is_template` and `instance.template_id` are allowed.
|
||||
*
|
||||
* @param config - Current config of the instance.
|
||||
* @param isTemplate - New value for `instance.is_template`.
|
||||
* @param templateId - New value for `instance.template_id`.
|
||||
* @throws {module:lib.ValidationError} if the template is not a template or would create a cycle.
|
||||
* @throws {module:lib.ConflictError} if the instance is assigned or still has inheritors.
|
||||
*/
|
||||
checkInheritance(config: lib.InstanceConfig, isTemplate: boolean, templateId: number | null): void {
|
||||
const instanceId = config.get("instance.id");
|
||||
if (isTemplate && config.get("instance.assigned_host") !== null) {
|
||||
throw new lib.ConflictError("Instance must be unassigned before it can be made a template");
|
||||
}
|
||||
if (!isTemplate && config.get("instance.is_template")) {
|
||||
const count = this.inheritorsOf(instanceId).length;
|
||||
if (count) {
|
||||
throw new lib.ConflictError(`Instance is the template of ${count} other instance(s)`);
|
||||
}
|
||||
}
|
||||
if (templateId === null) {
|
||||
return;
|
||||
}
|
||||
const template = this.records.get(templateId);
|
||||
if (!template) {
|
||||
throw new lib.NotFoundError(`Instance with ID ${templateId} does not exist`);
|
||||
}
|
||||
if (!template.config.get("instance.is_template")) {
|
||||
throw new lib.ValidationError(`Instance ${template.config.get("instance.name")} is not a template`);
|
||||
}
|
||||
const visited = new Set<number>();
|
||||
for (let id: number | null = templateId; id !== null && !visited.has(id);) {
|
||||
if (id === instanceId) {
|
||||
throw new lib.ValidationError("Templates cannot inherit from themselves");
|
||||
}
|
||||
visited.add(id);
|
||||
id = this.records.get(id)?.config.get("instance.template_id") ?? null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Copy the inheritable values from the template set in `instance.template_id`
|
||||
* into a config that is not yet part of the cluster and mark them inherited.
|
||||
*
|
||||
* @param config - Config of the instance to be created.
|
||||
* @param own - Fields set by the creator, object fields keep their properties as overrides.
|
||||
*/
|
||||
applyTemplate(config: lib.InstanceConfig, own: string[] = []): void {
|
||||
const template = this._templateOf(config);
|
||||
if (!template) {
|
||||
return;
|
||||
}
|
||||
const inherited: InheritedFields = {};
|
||||
for (const name of InstanceManager._inheritableFields()) {
|
||||
const def = lib.InstanceConfig.fieldDefinitions[name];
|
||||
if (def.type === "object") {
|
||||
inherited[name] = own.includes(name) ? Object.keys(config.get(name) as object ?? {}) : [];
|
||||
} else if (!own.includes(name)) {
|
||||
inherited[name] = true;
|
||||
}
|
||||
}
|
||||
config.set("instance.inherited_fields", inherited);
|
||||
config.update(InstanceManager._inheritedValues(config, template.config, Object.keys(inherited)), false);
|
||||
}
|
||||
|
||||
/**
|
||||
* Make a field, or a property of an object field, take its value from the template again.
|
||||
*
|
||||
* @param instanceId - ID of the instance to update.
|
||||
* @param field - Name of the field to inherit.
|
||||
* @param prop - Property of an object field to inherit, inherits all properties if not given.
|
||||
* @throws {module:lib.ValidationError} if the instance has no template or the field cannot be inherited.
|
||||
*/
|
||||
inheritField(instanceId: number, field: string, prop?: string): void {
|
||||
const instance = this.getForRequest(instanceId);
|
||||
if (!this._templateOf(instance.config)) {
|
||||
throw new lib.ValidationError("Instance does not have a template");
|
||||
}
|
||||
if (!lib.InstanceConfig.isInheritable(field)) {
|
||||
throw new lib.ValidationError(`Field ${field} cannot be inherited`);
|
||||
}
|
||||
const name = field as InheritableField;
|
||||
const inherited = { ...instance.config.get("instance.inherited_fields") };
|
||||
if (lib.InstanceConfig.fieldDefinitions[name].type !== "object") {
|
||||
inherited[field] = true;
|
||||
} else if (prop === undefined) {
|
||||
inherited[field] = [];
|
||||
} else {
|
||||
const entry = inherited[field];
|
||||
const overrides = entry instanceof Array ? entry : Object.keys(instance.config.get(name) as object ?? {});
|
||||
inherited[field] = overrides.filter(p => p !== prop);
|
||||
}
|
||||
instance.config.set("instance.inherited_fields", inherited);
|
||||
this._copyInheritedValues(instance, [field]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Stop inheriting the given field or properties, used when a value is explicitly set.
|
||||
*
|
||||
* @param instance - Instance the field was set on.
|
||||
* @param field - Name of the field set.
|
||||
* @param props - Properties set on an object field.
|
||||
*/
|
||||
overrideField(instance: InstanceRecord, field: string, props?: string[]): void {
|
||||
const entry = instance.config.get("instance.inherited_fields")[field];
|
||||
if (!instance.config.isInherited(field)) {
|
||||
return;
|
||||
}
|
||||
const inherited = { ...instance.config.get("instance.inherited_fields") };
|
||||
if (entry instanceof Array && props) {
|
||||
inherited[field] = [...new Set([...entry, ...props])];
|
||||
} else {
|
||||
delete inherited[field];
|
||||
}
|
||||
instance.config.set("instance.inherited_fields", inherited);
|
||||
}
|
||||
|
||||
private _templateOf(config: lib.InstanceConfig) {
|
||||
const templateId = config.get("instance.template_id");
|
||||
return templateId !== null ? this.records.get(templateId) : undefined;
|
||||
}
|
||||
|
||||
private static _inheritableFields() {
|
||||
return Object.keys(lib.InstanceConfig.fieldDefinitions).filter(
|
||||
name => lib.InstanceConfig.isInheritable(name)
|
||||
) as InheritableField[];
|
||||
}
|
||||
|
||||
/** Default value of a field for the given config */
|
||||
private static _defaultValue(name: InheritableField, config: lib.InstanceConfig): unknown {
|
||||
const def = lib.InstanceConfig.fieldDefinitions[name];
|
||||
if (name === "factorio.settings") {
|
||||
return InstanceManager.DefaultFactorioSettings;
|
||||
}
|
||||
return typeof def.initialValue === "function" ? def.initialValue(config) : def.initialValue ?? null;
|
||||
}
|
||||
|
||||
/** Values the given inherited fields take from the template, with object overrides applied */
|
||||
private static _inheritedValues(config: lib.InstanceConfig, template: lib.InstanceConfig, fields: string[]) {
|
||||
const inherited = config.get("instance.inherited_fields");
|
||||
const values: Record<string, any> = {};
|
||||
for (const field of fields) {
|
||||
const name = field as InheritableField;
|
||||
const entry = inherited[field];
|
||||
if (!entry) {
|
||||
continue;
|
||||
}
|
||||
const value = structuredClone(template.get(name)) as any;
|
||||
if (entry instanceof Array) {
|
||||
const own = config.get(name) as Record<string, unknown> ?? {};
|
||||
for (const prop of entry) {
|
||||
if (Object.hasOwn(own, prop)) {
|
||||
value[prop] = structuredClone(own[prop]);
|
||||
}
|
||||
}
|
||||
}
|
||||
values[field] = value;
|
||||
}
|
||||
return values;
|
||||
}
|
||||
|
||||
/** Update the given inherited fields of a live instance from its template */
|
||||
private _copyInheritedValues(instance: InstanceRecord, fields: string[]): void {
|
||||
const template = this._templateOf(instance.config);
|
||||
if (!template) {
|
||||
return;
|
||||
}
|
||||
const values = InstanceManager._inheritedValues(instance.config, template.config, fields);
|
||||
this._inheriting += 1;
|
||||
try {
|
||||
instance.config.update(values, true);
|
||||
} finally {
|
||||
this._inheriting -= 1;
|
||||
}
|
||||
}
|
||||
|
||||
/** Unlink a field, or the changed properties of an object field, edited on the instance */
|
||||
private _unlinkEditedField(instance: InstanceRecord, field: string, curr: unknown, prev: unknown): void {
|
||||
const entry = instance.config.get("instance.inherited_fields")[field];
|
||||
if (!(entry instanceof Array)) {
|
||||
this.overrideField(instance, field);
|
||||
return;
|
||||
}
|
||||
const currObj = curr as Record<string, unknown> ?? {};
|
||||
const prevObj = prev as Record<string, unknown> ?? {};
|
||||
const changed = Object.keys(currObj).filter(p => !isDeepStrictEqual(currObj[p], prevObj[p]));
|
||||
const removed = Object.keys(prevObj).filter(p => !Object.hasOwn(currObj, p));
|
||||
const overrides = [...new Set([...entry, ...changed])].filter(p => !removed.includes(p));
|
||||
const inherited = { ...instance.config.get("instance.inherited_fields"), [field]: overrides };
|
||||
instance.config.set("instance.inherited_fields", inherited);
|
||||
if (removed.length) {
|
||||
// Removed properties fall back to the template value
|
||||
this._copyInheritedValues(instance, [field]);
|
||||
}
|
||||
}
|
||||
|
||||
/** Recompute inherited fields after template_id changed, values equal to the template or default are inherited */
|
||||
private _linkMatchingFields(instance: InstanceRecord): void {
|
||||
const template = this._templateOf(instance.config);
|
||||
const inherited: InheritedFields = {};
|
||||
if (template) {
|
||||
for (const name of InstanceManager._inheritableFields()) {
|
||||
const value = instance.config.get(name) as any;
|
||||
const templateValue = template.config.get(name) as any;
|
||||
const defaultValue = InstanceManager._defaultValue(name, instance.config) as any;
|
||||
if (lib.InstanceConfig.fieldDefinitions[name].type === "object") {
|
||||
inherited[name] = Object.keys(value ?? {}).filter(prop => !(
|
||||
isDeepStrictEqual(value[prop], templateValue?.[prop])
|
||||
|| defaultValue && isDeepStrictEqual(value[prop], defaultValue[prop])
|
||||
) || name === "factorio.settings" && prop === "name");
|
||||
} else if (
|
||||
isDeepStrictEqual(value, templateValue)
|
||||
|| defaultValue !== undefined && isDeepStrictEqual(value, defaultValue)
|
||||
) {
|
||||
inherited[name] = true;
|
||||
}
|
||||
}
|
||||
}
|
||||
instance.config.set("instance.inherited_fields", inherited);
|
||||
this._copyInheritedValues(instance, Object.keys(inherited));
|
||||
}
|
||||
|
||||
/** Copy a changed value from a template to the instances inheriting it */
|
||||
private _updateInheritors(template: InstanceRecord, field: string, value: unknown): void {
|
||||
if (!lib.InstanceConfig.isInheritable(field)) {
|
||||
return;
|
||||
}
|
||||
for (const instance of this.inheritorsOf(template.id)) {
|
||||
if (!instance.config.isInherited(field)) {
|
||||
continue;
|
||||
}
|
||||
this._copyInheritedValues(instance, [field]);
|
||||
this._controller.instanceConfigUpdated(instance).catch(err => {
|
||||
logger.error(`Failed to send config of instance ${instance.id} to its host:\n${err.stack}`);
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------------- */
|
||||
/* Lifecycle */
|
||||
/* ------------------------------------------------------------------------- */
|
||||
@@ -137,12 +405,23 @@ export default class InstanceManager {
|
||||
}
|
||||
|
||||
const controllerName = this._controller.config.get("controller.name");
|
||||
instanceConfig.set("factorio.settings", {
|
||||
name: `${controllerName} - ${instanceConfig.get("instance.name")}`,
|
||||
description: `Clusterio instance for ${controllerName}`,
|
||||
...InstanceManager.DefaultFactorioSettings,
|
||||
...instanceConfig.get("factorio.settings"),
|
||||
});
|
||||
const serverName = `${controllerName} - ${instanceConfig.get("instance.name")}`;
|
||||
const settings = instanceConfig.get("factorio.settings");
|
||||
if (!instanceConfig.isInherited("factorio.settings")) {
|
||||
instanceConfig.set("factorio.settings", {
|
||||
name: serverName,
|
||||
description: `Clusterio instance for ${controllerName}`,
|
||||
...InstanceManager.DefaultFactorioSettings,
|
||||
...settings,
|
||||
});
|
||||
} else if (instanceConfig.isInherited("factorio.settings", "name")) {
|
||||
// Each instance gets its own server name
|
||||
instanceConfig.setProp("factorio.settings", "name", serverName);
|
||||
const inherited = instanceConfig.get("instance.inherited_fields");
|
||||
instanceConfig.set("instance.inherited_fields", {
|
||||
...inherited, "factorio.settings": [...inherited["factorio.settings"] as string[], "name"],
|
||||
});
|
||||
}
|
||||
|
||||
const instance = new InstanceRecord(instanceConfig, "unassigned");
|
||||
this.addInstanceHooks(instance);
|
||||
@@ -186,6 +465,9 @@ export default class InstanceManager {
|
||||
if (currentAssignedHost === hostId) {
|
||||
return;
|
||||
}
|
||||
if (hostId !== null && instance.config.get("instance.is_template")) {
|
||||
throw new lib.ValidationError("Templates cannot be assigned to a host");
|
||||
}
|
||||
|
||||
let newHostConnection: HostConnection | undefined;
|
||||
if (hostId !== null) {
|
||||
@@ -252,6 +534,10 @@ export default class InstanceManager {
|
||||
async deleteInstance(instanceId: number): Promise<void> {
|
||||
const instance = this.getForRequest(instanceId);
|
||||
const hostId = instance.config.get("instance.assigned_host");
|
||||
const inheritors = this.inheritorsOf(instanceId).length;
|
||||
if (inheritors) {
|
||||
throw new lib.ConflictError(`Instance is the template of ${inheritors} other instance(s)`);
|
||||
}
|
||||
|
||||
if (hostId !== null) {
|
||||
await this._controller.sendTo(
|
||||
|
||||
@@ -83,6 +83,9 @@ export default class InstanceRecord {
|
||||
this.startedAtMs,
|
||||
this.updatedAtMs,
|
||||
this.config.get("instance.exclude_from_start_all"),
|
||||
this.config.get("instance.is_template"),
|
||||
this.config.get("instance.template_id") ?? undefined,
|
||||
this.config.get("factorio.mod_pack_id") ?? undefined,
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
@@ -40,8 +40,8 @@ export default class UserManager {
|
||||
}
|
||||
|
||||
// We intentionally write the roles first because if it fails then the old user file will still contain them
|
||||
await lib.safeOutputFile(rolesFilePath, JSON.stringify(combinedJson.roles));
|
||||
await lib.safeOutputFile(usersFilePath, JSON.stringify(combinedJson.users));
|
||||
await lib.atomicOverwriteFile(rolesFilePath, JSON.stringify(combinedJson.roles));
|
||||
await lib.atomicOverwriteFile(usersFilePath, JSON.stringify(combinedJson.users));
|
||||
} catch (err: any) {
|
||||
if (err.code !== "ENOENT") {
|
||||
throw err;
|
||||
@@ -151,11 +151,34 @@ export default class UserManager {
|
||||
* @returns JWT access token for the user.
|
||||
*/
|
||||
signUserToken(user: UserRecord): string {
|
||||
return jwt.sign(
|
||||
{ aud: "user", user: user.id },
|
||||
// auth secret is never null after startup
|
||||
Buffer.from(this._controllerConfig.get("controller.auth_secret")!, "base64")
|
||||
);
|
||||
return jwt.sign({ aud: "user", user: user.id }, this._authSecret);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check a user token
|
||||
*
|
||||
* @param token - User token to check.
|
||||
* @returns the user the token was issued to.
|
||||
* @throws if the token is invalid, its user does not exist or it was issued before tokenValidAfter.
|
||||
*/
|
||||
verifyUserToken(token: string): User {
|
||||
const payload = jwt.verify(token, this._authSecret, { audience: "user" });
|
||||
if (typeof payload === "string") {
|
||||
throw new Error("unexpected JsonWebToken type");
|
||||
}
|
||||
const user = this.getByNameMutable(payload.user);
|
||||
if (!user) {
|
||||
throw new Error("invalid user");
|
||||
}
|
||||
if (!payload.iat || payload.iat < user.tokenValidAfter) {
|
||||
throw new Error("invalid token");
|
||||
}
|
||||
return user;
|
||||
}
|
||||
|
||||
private get _authSecret() {
|
||||
// auth secret is never null after startup
|
||||
return Buffer.from(this._controllerConfig.get("controller.auth_secret")!, "base64");
|
||||
}
|
||||
|
||||
/** Clear all player stats for specific instance */
|
||||
|
||||
@@ -30,6 +30,42 @@ const wsRejectedConnectionsCounter = new lib.Counter(
|
||||
"How many WebSocket connections have been rejected during the handshake on the controller"
|
||||
);
|
||||
|
||||
const wsReadyCounter = new lib.Counter(
|
||||
"clusterio_controller_websocket_ready_total",
|
||||
"How many WebSocket sessions have been established on the controller",
|
||||
{ labels: ["type"] }
|
||||
);
|
||||
|
||||
const wsResumeCounter = new lib.Counter(
|
||||
"clusterio_controller_websocket_resume_total",
|
||||
"How many WebSocket sessions have been resumed on the controller",
|
||||
{ labels: ["type"] }
|
||||
);
|
||||
|
||||
const wsDropCounter = new lib.Counter(
|
||||
"clusterio_controller_websocket_drop_total",
|
||||
"How many WebSocket sessions have lost their connection without closing on the controller",
|
||||
{ labels: ["type"] }
|
||||
);
|
||||
|
||||
const wsSessionTimeoutCounter = new lib.Counter(
|
||||
"clusterio_controller_websocket_session_timeout_total",
|
||||
"How many WebSocket sessions have timed out waiting for a resume on the controller",
|
||||
{ labels: ["type"] }
|
||||
);
|
||||
|
||||
const wsFailedResumeCounter = new lib.Counter(
|
||||
"clusterio_controller_websocket_failed_resume_total",
|
||||
"How many WebSocket resume attempts have been rejected due to an unknown or expired session on the controller"
|
||||
);
|
||||
|
||||
for (const type of ["host", "control"]) {
|
||||
wsReadyCounter.labels(type);
|
||||
wsResumeCounter.labels(type);
|
||||
wsDropCounter.labels(type);
|
||||
wsSessionTimeoutCounter.labels(type);
|
||||
}
|
||||
|
||||
/**
|
||||
* WebSocket server
|
||||
* @alias module:controller/src/WsServer
|
||||
@@ -240,6 +276,12 @@ ${err.stack}`
|
||||
this.activeConnectors.delete(sessionId);
|
||||
});
|
||||
|
||||
const type = dst.type === lib.Address.host ? "host" : "control";
|
||||
connector.on("connect", () => wsReadyCounter.labels(type).inc());
|
||||
connector.on("resume", () => wsResumeCounter.labels(type).inc());
|
||||
connector.on("drop", () => wsDropCounter.labels(type).inc());
|
||||
connector.on("timeout", () => wsSessionTimeoutCounter.labels(type).inc());
|
||||
|
||||
return [connector, sessionToken];
|
||||
}
|
||||
|
||||
@@ -252,21 +294,9 @@ ${err.stack}`
|
||||
}
|
||||
|
||||
try {
|
||||
// migrate: allow pre-rename tokens issued to hosts before alpha-14
|
||||
const tokenPayload = jwt.verify(data.token, this.controller.authSecret, { audience: ["host", "slave"] });
|
||||
if (typeof tokenPayload === "string") {
|
||||
throw new Error("unexpected JsonWebToken type");
|
||||
}
|
||||
|
||||
// migrate: allow pre-rename tokens issued to hosts before alpha-14
|
||||
if ((tokenPayload.host !== undefined ? tokenPayload.host : tokenPayload.slave) !== data.id) {
|
||||
if (this.controller.hosts.verifyHostToken(data.token).id !== data.id) {
|
||||
throw new Error("missmatched host id");
|
||||
}
|
||||
|
||||
let host = this.controller.hosts.get(data.id);
|
||||
if (!tokenPayload.iat || tokenPayload.iat < (host?.tokenValidAfter ?? 0)) {
|
||||
throw new Error("invalid token");
|
||||
}
|
||||
} catch (err: any) {
|
||||
logger.verbose(`WsServer | authentication failed for ${this.remoteAddr(req)}`);
|
||||
wsRejectedConnectionsCounter.inc();
|
||||
@@ -303,6 +333,13 @@ ${err.stack}`
|
||||
);
|
||||
}
|
||||
|
||||
// The host may have been revoked while waiting for the old connection to close.
|
||||
if (!this.controller.hosts.has(data.id)) {
|
||||
wsRejectedConnectionsCounter.inc();
|
||||
socket.close(lib.ConnectionClosed.Unauthorized, "Authentication failed: host was revoked");
|
||||
return;
|
||||
}
|
||||
|
||||
let [connector, sessionToken] = this.createSession(new lib.Address(lib.Address.host, data.id));
|
||||
|
||||
// Handle close before HostConnection does. This avoids a host
|
||||
@@ -325,18 +362,7 @@ ${err.stack}`
|
||||
async registerControl(data: lib.RegisterControlData, socket: WebSocket, req: IncomingMessage) {
|
||||
let user;
|
||||
try {
|
||||
const tokenPayload = jwt.verify(data.token, this.controller.authSecret, { audience: "user" });
|
||||
if (typeof tokenPayload === "string") {
|
||||
throw new Error("unexpected JsonWebToken type");
|
||||
}
|
||||
|
||||
user = this.controller.users.getByNameMutable(tokenPayload.user);
|
||||
if (!user) {
|
||||
throw new Error("invalid user");
|
||||
}
|
||||
if ((tokenPayload.iat || 0) < user.tokenValidAfter) {
|
||||
throw new Error("invalid token");
|
||||
}
|
||||
user = this.controller.users.verifyUserToken(data.token);
|
||||
user.checkPermission("core.control.connect");
|
||||
|
||||
} catch (err: any) {
|
||||
@@ -383,6 +409,7 @@ ${err.stack}`
|
||||
}
|
||||
|
||||
} catch (err) {
|
||||
wsFailedResumeCounter.inc();
|
||||
socket.send(JSON.stringify(new lib.MessageInvalidate()));
|
||||
this.attachHandler(socket, req);
|
||||
return;
|
||||
|
||||
@@ -7,13 +7,17 @@ import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
|
||||
|
||||
type WsServerConnectorEvents = {
|
||||
"timeout": [],
|
||||
};
|
||||
|
||||
/**
|
||||
* Connector for controller connections
|
||||
*
|
||||
* @extends module:lib.WebSocketBaseConnector
|
||||
* @alias module:controller/src/WsServerConnector
|
||||
*/
|
||||
export default class WsServerConnector extends lib.WebSocketBaseConnector {
|
||||
export default class WsServerConnector extends lib.WebSocketBaseConnector<WsServerConnectorEvents> {
|
||||
_timeoutId: ReturnType<typeof setTimeout> | null = null;
|
||||
|
||||
constructor(
|
||||
@@ -119,6 +123,7 @@ export default class WsServerConnector extends lib.WebSocketBaseConnector {
|
||||
|
||||
_timedOut() {
|
||||
logger.verbose(`Connector | Connection to ${this.dst} timed out`);
|
||||
this.emit("timeout");
|
||||
this._close();
|
||||
}
|
||||
|
||||
|
||||
+425
-223
@@ -1,11 +1,11 @@
|
||||
import type { Application, Request, Response } from "express";
|
||||
import express, { type Application, type Request, type Response } from "express";
|
||||
import Controller from "./Controller.js";
|
||||
import HostPairingManager, { HostPairingError } from "./HostPairingManager.js";
|
||||
|
||||
import busboy from "busboy";
|
||||
import crypto from "crypto";
|
||||
import events from "events";
|
||||
import fs from "node:fs/promises";
|
||||
import jwt from "jsonwebtoken";
|
||||
import path from "path";
|
||||
import nodeStream from "stream";
|
||||
import util from "util";
|
||||
@@ -188,17 +188,7 @@ function validateHostToken(req: Request, res: Response, next: any) {
|
||||
}
|
||||
|
||||
try {
|
||||
const tokenPayload = jwt.verify(token, req.app.locals.controller.authSecret, { audience: "host" });
|
||||
if (typeof tokenPayload === "string") {
|
||||
throw new Error("unexpected JsonWebToken type");
|
||||
}
|
||||
let host = req.app.locals.controller.hosts.get(tokenPayload.host);
|
||||
if (!host) {
|
||||
throw new Error("invalid host");
|
||||
}
|
||||
if (!tokenPayload.iat || tokenPayload.iat < (host.tokenValidAfter ?? 0)) {
|
||||
throw new Error("invalid token");
|
||||
}
|
||||
req.app.locals.controller.hosts.verifyHostToken(token);
|
||||
} catch (err) {
|
||||
res.sendStatus(401);
|
||||
return;
|
||||
@@ -215,19 +205,7 @@ function validateUserToken(req: Request, res: Response, next: any) {
|
||||
}
|
||||
|
||||
try {
|
||||
const tokenPayload = jwt.verify(token, req.app.locals.controller.authSecret, { audience: "user" });
|
||||
if (typeof tokenPayload === "string") {
|
||||
throw new Error("unexpected JsonWebToken type");
|
||||
}
|
||||
let user = req.app.locals.controller.users.getByName(tokenPayload.user);
|
||||
if (!user) {
|
||||
throw new Error("invalid user");
|
||||
}
|
||||
if (!tokenPayload.iat || tokenPayload.iat < user.tokenValidAfter) {
|
||||
throw new Error("invalid token");
|
||||
}
|
||||
res.locals.user = user;
|
||||
|
||||
res.locals.user = req.app.locals.controller.users.verifyUserToken(token);
|
||||
} catch (err) {
|
||||
res.sendStatus(401);
|
||||
return;
|
||||
@@ -236,6 +214,105 @@ function validateUserToken(req: Request, res: Response, next: any) {
|
||||
next();
|
||||
}
|
||||
|
||||
// Responds with the status of a pairing error, returns false for other errors.
|
||||
function sendHostPairingError(res: Response, err: unknown) {
|
||||
if (!(err instanceof HostPairingError)) {
|
||||
return false;
|
||||
}
|
||||
if (err.retryAfter !== undefined) {
|
||||
res.set("Retry-After", String(err.retryAfter));
|
||||
}
|
||||
res.status(err.status).json({ error: err.message });
|
||||
return true;
|
||||
}
|
||||
|
||||
// Checks recovery mode and the request id for the pairing endpoints, returns false if responded to.
|
||||
function checkHostPairingRequest(req: Request, res: Response, needsRequestId: boolean) {
|
||||
if (req.app.locals.controller.recoveryMode) {
|
||||
res.status(503).json({ error: "Controller is in recovery mode" });
|
||||
return false;
|
||||
}
|
||||
if (needsRequestId && typeof req.body?.requestId !== "string") {
|
||||
res.status(400).json({ error: "requestId is required" });
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
// Request from a host for a host to join the cluster.
|
||||
function createHostPairing(req: Request, res: Response) {
|
||||
if (!checkHostPairingRequest(req, res, false)) {
|
||||
return;
|
||||
}
|
||||
const controller = req.app.locals.controller;
|
||||
const remoteAddress = controller.wsServer.remoteAddr(req);
|
||||
try {
|
||||
const name = HostPairingManager.validateName(req.body?.name);
|
||||
const version = typeof req.body?.version === "string" ? req.body.version.slice(0, 64) : "";
|
||||
|
||||
// A user allowed to approve hosts can skip the wait by passing their token.
|
||||
const token = getAccessToken(req);
|
||||
if (token !== undefined) {
|
||||
let user;
|
||||
try {
|
||||
user = controller.users.verifyUserToken(token);
|
||||
} catch (err) {
|
||||
res.status(401).json({ error: "Invalid user token" });
|
||||
return;
|
||||
}
|
||||
try {
|
||||
user.checkPermission("core.host.approve");
|
||||
} catch (err) {
|
||||
logger.audit(
|
||||
`User ${user.name} tried to approve host ${name} from ${remoteAddress} without permission`
|
||||
);
|
||||
res.status(403).json({ error: `User ${user.name} is not allowed to approve hosts` });
|
||||
return;
|
||||
}
|
||||
const host = controller.hosts.createHost(name);
|
||||
logger.audit(
|
||||
`User ${user.name} approved host ${host.name} (${host.id}) from ${remoteAddress} with their token`
|
||||
);
|
||||
res.status(200).json({ hostId: host.id, token: controller.hosts.signHostToken(host.id), name: host.name });
|
||||
return;
|
||||
}
|
||||
|
||||
res.status(202).json(controller.hostPairing.create(name, version, remoteAddress));
|
||||
} catch (err) {
|
||||
if (!sendHostPairingError(res, err)) {
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Poll from a host for the result of its request.
|
||||
function pollHostPairing(req: Request, res: Response) {
|
||||
if (!checkHostPairingRequest(req, res, true)) {
|
||||
return;
|
||||
}
|
||||
try {
|
||||
const result = req.app.locals.controller.hostPairing.poll(req.body.requestId);
|
||||
if (result) {
|
||||
res.status(200).json(result);
|
||||
} else {
|
||||
res.status(202).json({ status: "pending" });
|
||||
}
|
||||
} catch (err) {
|
||||
if (!sendHostPairingError(res, err)) {
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Cancel from a host that stopped waiting.
|
||||
function cancelHostPairing(req: Request, res: Response) {
|
||||
if (!checkHostPairingRequest(req, res, true)) {
|
||||
return;
|
||||
}
|
||||
req.app.locals.controller.hostPairing.cancel(req.body.requestId);
|
||||
res.sendStatus(204);
|
||||
}
|
||||
|
||||
// Handle an uploaded export package.
|
||||
async function uploadExport(req: Request, res: Response) {
|
||||
if (req.get("Content-Type") !== "application/zip") {
|
||||
@@ -290,7 +367,7 @@ async function uploadExport(req: Request, res: Response) {
|
||||
let { name, ext } = path.posix.parse(filePath);
|
||||
let hash = await lib.hashStream(await zip.openStream(file));
|
||||
assets[name] = `${name}.${hash}${ext}`;
|
||||
await lib.safeOutputFile(path.join("static", `${name}.${hash}${ext}`), content);
|
||||
await lib.atomicOverwriteFile(path.join("static", `${name}.${hash}${ext}`), content);
|
||||
}
|
||||
|
||||
modPack.exportManifest = new lib.ExportManifest(assets, new Date().toISOString());
|
||||
@@ -300,6 +377,30 @@ async function uploadExport(req: Request, res: Response) {
|
||||
res.sendStatus(200);
|
||||
}
|
||||
|
||||
// Reached when no static file matched, drops exports whose files were removed
|
||||
export function missingExportAsset(req: Request, res: Response, next: any) {
|
||||
const file = req.path.slice(1);
|
||||
if (!["GET", "HEAD"].includes(req.method) || !file) {
|
||||
next();
|
||||
return;
|
||||
}
|
||||
const modPacks = res.app.locals.controller.modPacks;
|
||||
const affected = [...modPacks.valuesMutable()].filter(
|
||||
modPack => modPack.exportManifest && Object.values(modPack.exportManifest.assets).includes(file)
|
||||
);
|
||||
if (!affected.length) {
|
||||
next();
|
||||
return;
|
||||
}
|
||||
for (const modPack of affected) {
|
||||
Controller.dropExport(modPack, `${file} was removed from disk`);
|
||||
}
|
||||
modPacks.setMany(affected);
|
||||
res.status(404).type("text/plain").send(
|
||||
`Export data file ${file} is missing, run export-data on an instance to regenerate it`
|
||||
);
|
||||
}
|
||||
|
||||
type ProxyStreamEvents = {
|
||||
"error": [ err: any ],
|
||||
"close": [],
|
||||
@@ -316,6 +417,9 @@ export interface ProxyStream {
|
||||
filename: string | null;
|
||||
events: events.EventEmitter<ProxyStreamEvents>;
|
||||
timeout: ReturnType<typeof setTimeout>;
|
||||
closed: boolean;
|
||||
/** Bytes the receiver has taken, set once the stream is flowing */
|
||||
bytesTaken?: () => number;
|
||||
}
|
||||
|
||||
export async function createProxyStream(app: Application): Promise<ProxyStream> {
|
||||
@@ -332,8 +436,10 @@ export async function createProxyStream(app: Application): Promise<ProxyStream>
|
||||
timeout: setTimeout(() => {
|
||||
stream.events.emit("timeout");
|
||||
}, app.locals.controller.config.get("controller.proxy_stream_timeout") * 1000),
|
||||
closed: false,
|
||||
};
|
||||
stream.events.on("close", () => {
|
||||
stream.closed = true;
|
||||
clearTimeout(stream.timeout);
|
||||
app.locals.streams.delete(id);
|
||||
});
|
||||
@@ -344,24 +450,113 @@ export async function createProxyStream(app: Application): Promise<ProxyStream>
|
||||
return stream;
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for the HTTP servers the routes are served from
|
||||
*
|
||||
* Node closes requests that have not been received in full after 5 minutes
|
||||
* by default, which would cut off large uploads over slow connections.
|
||||
* Requests are instead closed by guardRequest when they move too little.
|
||||
* Turning the limit off also turns off the limit on receiving the headers,
|
||||
* which guardRequest can't cover, so that is set back to its default.
|
||||
*/
|
||||
export const httpServerOptions = { requestTimeout: 0, headersTimeout: 60_000 };
|
||||
|
||||
/** Time an upload is read and thrown away after it was answered, before its connection is closed */
|
||||
const answeredUploadDrainMs = 1000;
|
||||
|
||||
/**
|
||||
* Guard requests against wasted and stalled transfers
|
||||
*
|
||||
* Node reads and discards the body of a request answered before it was
|
||||
* read to keep the connection open. A client, or a proxy in front of the
|
||||
* controller, that keeps sending would upload the whole body for nothing,
|
||||
* 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 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, burstAllowanceBytes: number) {
|
||||
return function(req: Request, res: Response, next: any) {
|
||||
const socket = req.socket;
|
||||
res.once("finish", () => {
|
||||
if (req.complete || socket.destroyed) {
|
||||
return;
|
||||
}
|
||||
const timeout = setTimeout(() => socket.destroy(), answeredUploadDrainMs);
|
||||
const onClose = () => clearTimeout(timeout);
|
||||
socket.once("close", onClose);
|
||||
// The connection may be kept open for more requests, so don't leave a listener on it
|
||||
req.once("end", () => {
|
||||
clearTimeout(timeout);
|
||||
socket.off("close", onClose);
|
||||
});
|
||||
});
|
||||
|
||||
const bytesReceived = () => socket.bytesRead;
|
||||
let measuredBytes: (() => number) | undefined = bytesReceived;
|
||||
let lastBytes = bytesReceived();
|
||||
const check = setInterval(() => {
|
||||
const stream: ProxyStream | undefined = res.locals.proxyStream;
|
||||
let currentBytes: (() => number) | undefined;
|
||||
if (stream && !stream.closed) {
|
||||
currentBytes = stream.bytesTaken;
|
||||
} else if (!req.complete) {
|
||||
currentBytes = bytesReceived;
|
||||
}
|
||||
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.
|
||||
measuredBytes = currentBytes;
|
||||
lastBytes = currentBytes ? currentBytes() : 0;
|
||||
return;
|
||||
}
|
||||
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 ${bytes - lastBytes} bytes in ${intervalS} seconds, ` +
|
||||
`less than the ${requiredBytes} required for ${minSpeedKiBps} KiB/s`
|
||||
);
|
||||
socket.destroy();
|
||||
}
|
||||
lastBytes = bytes;
|
||||
}, checkIntervalMs);
|
||||
res.once("close", () => clearInterval(check));
|
||||
next();
|
||||
};
|
||||
}
|
||||
|
||||
async function putStream(req: Request<{ id: string }>, res: Response) {
|
||||
const stream = req.app.locals.streams.get(req.params.id);
|
||||
if (!stream || stream.source) {
|
||||
res.sendStatus(404);
|
||||
return;
|
||||
}
|
||||
res.locals.proxyStream = stream;
|
||||
stream.source = req;
|
||||
stream.mime = req.get("Content-Type");
|
||||
stream.size = req.get("Content-Length");
|
||||
|
||||
stream.events.emit("source");
|
||||
stream.events.on("close", () => {
|
||||
if (!stream.flowing) {
|
||||
req.resume();
|
||||
res.sendStatus(500);
|
||||
} else {
|
||||
res.sendStatus(200);
|
||||
}
|
||||
// The stream also closes when it timed out or the receiver disconnected.
|
||||
res.sendStatus(stream.flowing && req.complete ? 200 : 500);
|
||||
});
|
||||
}
|
||||
|
||||
@@ -375,9 +570,22 @@ function startStream(res: Response, stream: ProxyStream) {
|
||||
} else {
|
||||
res.append("Content-Disposition", "attachment");
|
||||
}
|
||||
stream.source!.pipe(res);
|
||||
const source = stream.source!;
|
||||
const socket = res.socket!;
|
||||
source.pipe(res);
|
||||
stream.flowing = true;
|
||||
// Counts completed writes, so data waiting in a buffer is not progress.
|
||||
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) {
|
||||
res.destroy();
|
||||
}
|
||||
};
|
||||
source.once("close", onSourceClose);
|
||||
res.on("close", () => {
|
||||
source.off("close", onSourceClose);
|
||||
source.unpipe(res);
|
||||
stream.events.emit("close");
|
||||
});
|
||||
clearTimeout(stream.timeout);
|
||||
@@ -389,6 +597,7 @@ async function getStream(req: Request<{ id: string }>, res: Response) {
|
||||
res.sendStatus(404);
|
||||
return;
|
||||
}
|
||||
res.locals.proxyStream = stream;
|
||||
|
||||
if (stream.source) {
|
||||
startStream(res, stream);
|
||||
@@ -408,6 +617,141 @@ const zipMimes = [
|
||||
|
||||
const contentTypeRegExp = /^([!#$%&'*+\-.^_`|~0-9A-Za-z]+\/[!#$%&'*+\-.^_`|~0-9A-Za-z]+)/;
|
||||
|
||||
/** Error in an upload that is the fault of the request */
|
||||
class UploadRequestError extends Error {
|
||||
constructor(message: string, public status = 400) {
|
||||
super(message);
|
||||
}
|
||||
}
|
||||
|
||||
interface UploadedZip {
|
||||
/** Content of the file, ends with an error if the upload is cut short */
|
||||
stream: nodeStream.Readable;
|
||||
filename: string;
|
||||
mime: string;
|
||||
/** Form fields received before the file, or the query parameters of a zip upload */
|
||||
fields: Map<string, string>;
|
||||
/** True if the file is part of a multipart form */
|
||||
multipart: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* Receive zip files uploaded as either the request body or a multipart form
|
||||
*
|
||||
* Responds with the first error, without reading the rest of the upload.
|
||||
* Errors other than UploadRequestError are logged and responded to with 500.
|
||||
* @param req - The upload.
|
||||
* @param res - Response to the upload.
|
||||
* @param kind - What is uploaded, for the log.
|
||||
* @param handleFile -
|
||||
* Called with each file, the next file is not read before the stream of
|
||||
* the previous has been consumed.
|
||||
* @returns true if all files were handled, false if an error was responded with.
|
||||
*/
|
||||
async function receiveZipUpload(
|
||||
req: Request,
|
||||
res: Response,
|
||||
kind: string,
|
||||
handleFile: (file: UploadedZip) => Promise<void>,
|
||||
): Promise<boolean> {
|
||||
function fail(err: any) {
|
||||
if (res.headersSent) {
|
||||
return;
|
||||
}
|
||||
if (err instanceof UploadRequestError) {
|
||||
res.status(err.status).json({ request_errors: [err.message] });
|
||||
return;
|
||||
}
|
||||
logger.error(`Error uploading ${kind}: ${err.message}`);
|
||||
res.status(500).json({ errors: [err.message], request_errors: [] });
|
||||
}
|
||||
|
||||
const match = contentTypeRegExp.exec(req.get("Content-Type") || "");
|
||||
const contentMime = match ? match[1].toLowerCase() : "";
|
||||
|
||||
if (zipMimes.includes(contentMime)) {
|
||||
try {
|
||||
const filename = req.query.filename;
|
||||
if (typeof filename !== "string") {
|
||||
throw new UploadRequestError("Missing or invalid filename parameter");
|
||||
}
|
||||
if (!filename.endsWith(".zip")) {
|
||||
throw new UploadRequestError("filename must end with .zip");
|
||||
}
|
||||
const fields = new Map<string, string>();
|
||||
for (const [name, value] of Object.entries(req.query)) {
|
||||
if (typeof value === "string") {
|
||||
fields.set(name, value);
|
||||
}
|
||||
}
|
||||
await handleFile({ stream: req, filename, mime: contentMime, fields, multipart: false });
|
||||
} catch (err: any) {
|
||||
fail(err);
|
||||
return false;
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
if (contentMime !== "multipart/form-data") {
|
||||
fail(new UploadRequestError("invalid Content-Type", 415));
|
||||
return false;
|
||||
}
|
||||
|
||||
let parser: busboy.Busboy;
|
||||
try {
|
||||
parser = busboy({ headers: req.headers });
|
||||
} catch (err: any) {
|
||||
fail(new UploadRequestError(err.message));
|
||||
return false;
|
||||
}
|
||||
|
||||
return await new Promise<boolean>(resolve => {
|
||||
const fields = new Map<string, string>();
|
||||
const tasks: Promise<void>[] = [];
|
||||
let failed = false;
|
||||
function onError(err: any) {
|
||||
if (failed) {
|
||||
return;
|
||||
}
|
||||
failed = true;
|
||||
fail(err);
|
||||
// Stop reading the upload, this ends the file being read with an error.
|
||||
req.unpipe(parser);
|
||||
parser.destroy();
|
||||
resolve(false);
|
||||
}
|
||||
parser.on("field", (name, value) => {
|
||||
fields.set(name, value);
|
||||
});
|
||||
parser.on("file", (name, stream, { filename, mimeType }) => {
|
||||
// The handler may be done with the stream by the time it fails.
|
||||
stream.on("error", () => {});
|
||||
if (failed) {
|
||||
stream.resume();
|
||||
} else if (!zipMimes.includes(mimeType)) {
|
||||
onError(new UploadRequestError("invalid file Content-Type"));
|
||||
} else if (!filename?.endsWith(".zip")) {
|
||||
onError(new UploadRequestError("filename must end with .zip"));
|
||||
} else {
|
||||
tasks.push(handleFile({
|
||||
stream, filename, mime: mimeType, fields: new Map(fields), multipart: true,
|
||||
}).catch(onError));
|
||||
}
|
||||
});
|
||||
parser.on("error", onError);
|
||||
parser.on("close", () => {
|
||||
Promise.all(tasks).then(() => resolve(!failed));
|
||||
});
|
||||
// Pipe does not end the parser if the upload is cut short.
|
||||
req.once("close", () => {
|
||||
if (!req.complete) {
|
||||
onError(new Error("Upload was aborted"));
|
||||
}
|
||||
});
|
||||
req.pipe(parser);
|
||||
});
|
||||
}
|
||||
|
||||
async function uploadSave(req: Request, res: Response) {
|
||||
try {
|
||||
res.locals.user.checkPermission("core.instance.save.upload");
|
||||
@@ -416,26 +760,25 @@ async function uploadSave(req: Request, res: Response) {
|
||||
return;
|
||||
}
|
||||
|
||||
let contentType = req.get("Content-Type") || "";
|
||||
let match = contentTypeRegExp.exec(contentType);
|
||||
if (!match) {
|
||||
res.status(415).json({ request_errors: ["invalid Content-Type"] });
|
||||
return;
|
||||
}
|
||||
let contentMime = match[1].toLowerCase();
|
||||
|
||||
let tasks = [];
|
||||
let errors: string[] = [];
|
||||
let requestErrors = [];
|
||||
let saves: string[] = [];
|
||||
async function handleFile(file: UploadedZip) {
|
||||
const value = file.fields.get("instance_id");
|
||||
if (value === undefined && file.multipart) {
|
||||
throw new UploadRequestError("instance_id must come before files uploaded");
|
||||
}
|
||||
const instanceId = Number.parseInt(String(value), 10);
|
||||
if (Number.isNaN(instanceId)) {
|
||||
throw new UploadRequestError(
|
||||
file.multipart ? "invalid instance_id" : "Missing or invalid instance_id parameter"
|
||||
);
|
||||
}
|
||||
|
||||
async function handleFile(instanceId:number, stream: nodeStream.Readable, filename: string, streamMime: string) {
|
||||
let proxyStream = await createProxyStream(req.app);
|
||||
proxyStream.source = stream;
|
||||
proxyStream.mime = streamMime;
|
||||
res.locals.proxyStream = proxyStream;
|
||||
proxyStream.source = file.stream;
|
||||
proxyStream.mime = file.mime;
|
||||
let timeout = new Promise<never>((_, reject) => {
|
||||
proxyStream.events.on("timeout", () => {
|
||||
stream.resume();
|
||||
reject(new Error("Timed out establishing stream to host"));
|
||||
});
|
||||
});
|
||||
@@ -446,7 +789,7 @@ async function uploadSave(req: Request, res: Response) {
|
||||
new lib.InstancePullSaveRequest(
|
||||
instanceId,
|
||||
proxyStream.id,
|
||||
filename,
|
||||
file.filename,
|
||||
)
|
||||
),
|
||||
timeout,
|
||||
@@ -455,90 +798,13 @@ async function uploadSave(req: Request, res: Response) {
|
||||
|
||||
} catch (err: any) {
|
||||
proxyStream.events.emit("close");
|
||||
logger.error(`Error uploading save: ${err.message}`);
|
||||
errors.push(err.message);
|
||||
stream.resume();
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
if (contentMime === "multipart/form-data") {
|
||||
await new Promise(resolve => {
|
||||
let instanceId: number | undefined;
|
||||
function fileHandler(
|
||||
name: string,
|
||||
stream: nodeStream.Readable,
|
||||
{ filename, mimeType }: { filename: string, mimeType: string }
|
||||
) {
|
||||
if (instanceId === undefined) {
|
||||
requestErrors.push("instance_id must come before files uploaded");
|
||||
}
|
||||
if (!zipMimes.includes(mimeType)) {
|
||||
requestErrors.push("invalid file Content-Type");
|
||||
}
|
||||
if (!filename.endsWith(".zip")) {
|
||||
requestErrors.push("filename must end with .zip");
|
||||
}
|
||||
if (errors.length || requestErrors.length) {
|
||||
stream.resume();
|
||||
return;
|
||||
}
|
||||
tasks.push(handleFile(instanceId as number, stream, filename, mimeType));
|
||||
}
|
||||
let parser = busboy({ headers: req.headers });
|
||||
parser.on("file", fileHandler);
|
||||
parser.on("field", (name, value, info) => {
|
||||
if (name === "instance_id") {
|
||||
instanceId = Number.parseInt(value, 10);
|
||||
if (Number.isNaN(instanceId)) {
|
||||
requestErrors.push("invalid instance_id");
|
||||
}
|
||||
}
|
||||
});
|
||||
parser.on("close", resolve);
|
||||
parser.on("error", (err: any) => {
|
||||
logger.error(`Error parsing multipart request in upload-save:\n${err.stack}`);
|
||||
errors.push(err.message);
|
||||
});
|
||||
req.pipe(parser);
|
||||
});
|
||||
|
||||
} else if (zipMimes.includes(contentMime)) {
|
||||
let filename = req.query.filename;
|
||||
if (typeof filename !== "string") {
|
||||
requestErrors.push("Missing or invalid filename parameter");
|
||||
} else if (!filename.endsWith(".zip")) {
|
||||
requestErrors.push("filename must end with .zip");
|
||||
}
|
||||
let instanceId = Number.parseInt(String(req.query.instance_id), 10);
|
||||
if (Number.isNaN(instanceId)) {
|
||||
requestErrors.push("Missing or invalid instance_id parameter");
|
||||
}
|
||||
|
||||
if (errors.length || requestErrors.length) {
|
||||
req.resume();
|
||||
} else {
|
||||
tasks.push(handleFile(instanceId, req, filename as string, contentMime));
|
||||
}
|
||||
|
||||
} else {
|
||||
res.status(415).json({ request_errors: ["invalid Content-Type"] });
|
||||
return;
|
||||
if (await receiveZipUpload(req, res, "save", handleFile)) {
|
||||
res.json({ saves });
|
||||
}
|
||||
|
||||
await Promise.all(tasks);
|
||||
|
||||
if (errors.length) {
|
||||
res.status(500);
|
||||
res.json({ errors, request_errors: requestErrors });
|
||||
return;
|
||||
}
|
||||
if (requestErrors.length) {
|
||||
res.status(400);
|
||||
res.json({ request_errors: requestErrors });
|
||||
return;
|
||||
}
|
||||
|
||||
res.json({ saves });
|
||||
}
|
||||
|
||||
function checkModName(name: string) {
|
||||
@@ -557,50 +823,28 @@ async function uploadMod(req: Request, res: Response) {
|
||||
return;
|
||||
}
|
||||
|
||||
let contentType = req.get("Content-Type")!;
|
||||
let match = contentTypeRegExp.exec(contentType);
|
||||
if (!match) {
|
||||
res.status(415).json({ request_errors: ["invalid Content-Type"] });
|
||||
return;
|
||||
}
|
||||
let contentMime = match[1].toLowerCase();
|
||||
|
||||
let tasks = [];
|
||||
let errors: string[] = [];
|
||||
let requestErrors = [];
|
||||
let mods: any[] = [];
|
||||
|
||||
async function handleFile(stream: nodeStream.Readable, filename: string) {
|
||||
try {
|
||||
checkModName(filename);
|
||||
|
||||
} catch (err: any) {
|
||||
logger.error(`Error uploading mod: ${err.message}`);
|
||||
errors.push(err.message);
|
||||
stream.resume();
|
||||
return;
|
||||
}
|
||||
async function handleFile(file: UploadedZip) {
|
||||
checkModName(file.filename);
|
||||
|
||||
const modsDirectory = req.app.locals.controller.config.get("controller.mods_directory");
|
||||
const filePath = path.join(modsDirectory, filename);
|
||||
const filePath = path.join(modsDirectory, file.filename);
|
||||
const [tempFilePath, writeStream] = await lib.createTempWriteStream(filePath);
|
||||
|
||||
try {
|
||||
stream.pipe(writeStream);
|
||||
await finished(writeStream);
|
||||
file.stream.pipe(writeStream);
|
||||
// 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);
|
||||
mods.push(modInfo.toJSON());
|
||||
|
||||
} catch (err: any) {
|
||||
logger.error(`Error uploading mod: ${err.message}`);
|
||||
errors.push(err.message);
|
||||
stream.resume();
|
||||
|
||||
// Attempt to clean up.
|
||||
file.stream.unpipe(writeStream);
|
||||
writeStream.destroy();
|
||||
|
||||
try {
|
||||
@@ -610,82 +854,40 @@ async function uploadMod(req: Request, res: Response) {
|
||||
logger.error(`Error removing ${tempFilePath}: ${unlinkErr.message}`);
|
||||
}
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
if (contentMime === "multipart/form-data") {
|
||||
await new Promise(resolve => {
|
||||
function fileHandler(
|
||||
name: string,
|
||||
stream: nodeStream.Readable,
|
||||
{ filename, mimeType }: { filename: string, mimeType: string }
|
||||
) {
|
||||
if (!zipMimes.includes(mimeType)) {
|
||||
requestErrors.push("invalid file Content-Type");
|
||||
}
|
||||
if (!filename.endsWith(".zip")) {
|
||||
requestErrors.push("filename must end with .zip");
|
||||
}
|
||||
if (errors.length || requestErrors.length) {
|
||||
stream.resume();
|
||||
return;
|
||||
}
|
||||
tasks.push(handleFile(stream, filename));
|
||||
}
|
||||
|
||||
let parser = busboy({ headers: req.headers });
|
||||
parser.on("file", fileHandler);
|
||||
parser.on("close", resolve);
|
||||
parser.on("error", (err: any) => {
|
||||
logger.error(`Error parsing multipart request in upload-mod:\n${err.stack}`);
|
||||
errors.push(err.message);
|
||||
});
|
||||
req.pipe(parser);
|
||||
});
|
||||
|
||||
} else if (zipMimes.includes(contentMime)) {
|
||||
let filename = req.query.filename;
|
||||
if (typeof filename !== "string") {
|
||||
requestErrors.push("Missing or invalid filename parameter");
|
||||
} else if (!filename.endsWith(".zip")) {
|
||||
requestErrors.push("filename must end with .zip");
|
||||
}
|
||||
|
||||
if (errors.length || requestErrors.length) {
|
||||
req.resume();
|
||||
} else {
|
||||
tasks.push(handleFile(req, filename as string));
|
||||
}
|
||||
|
||||
} else {
|
||||
res.status(415).json({ request_errors: ["invalid Content-Type"] });
|
||||
return;
|
||||
if (await receiveZipUpload(req, res, "mod", handleFile)) {
|
||||
res.json({ mods });
|
||||
}
|
||||
|
||||
await Promise.all(tasks);
|
||||
|
||||
if (errors.length) {
|
||||
res.status(500);
|
||||
res.json({ errors, request_errors: requestErrors });
|
||||
return;
|
||||
}
|
||||
if (requestErrors.length) {
|
||||
res.status(400);
|
||||
res.json({ request_errors: requestErrors });
|
||||
return;
|
||||
}
|
||||
|
||||
res.json({ mods });
|
||||
}
|
||||
|
||||
|
||||
export function addRouteHandlers(app: Application) {
|
||||
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)
|
||||
);
|
||||
app.get("/api/plugins", getPlugins);
|
||||
app.get("/api/cluster-name", getClusterName);
|
||||
// Set before parsing so errors from the body parser and token check are not cached either.
|
||||
const noStore = (req: Request, res: Response, next: any) => {
|
||||
res.set("Cache-Control", "no-store");
|
||||
next();
|
||||
};
|
||||
const pairingJson = express.json({ limit: "4kb" });
|
||||
app.post("/api/host-pairing", noStore, pairingJson, createHostPairing);
|
||||
app.post("/api/host-pairing/poll", noStore, pairingJson, pollHostPairing);
|
||||
app.post("/api/host-pairing/cancel", noStore, pairingJson, cancelHostPairing);
|
||||
app.get("/api/host-pairing/check", noStore, validateHostToken, (req: Request, res: Response) => {
|
||||
res.json({ valid: true });
|
||||
});
|
||||
app.put("/api/upload-export",
|
||||
validateHostToken,
|
||||
(req:Request, res:Response, next:any) => uploadExport(req, res).catch(next)
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
// This needs to be a separate file due to ECMAScript Modules evaluating code in
|
||||
// imported modules before any code in the file that imports it.
|
||||
(global as any).lazySchemaCompilation = true;
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"entryPoints": ["index.ts"],
|
||||
"includeVersion": true
|
||||
}
|
||||
@@ -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 {
|
||||
|
||||
@@ -4,3 +4,113 @@ Installer for Clusterio.
|
||||
|
||||
Install the latest [Node.js LTS release](https://nodejs.org/en/download) before running the installer.
|
||||
See [the Clusterio installation guide](https://github.com/clusterio/clusterio#installation) for platform-specific instructions.
|
||||
|
||||
Run the installer in a new empty directory:
|
||||
|
||||
npm init "@clusterio"
|
||||
|
||||
It asks which components to install and how to set them up.
|
||||
Every question can be answered with an option instead, pass options to the installer after `--`:
|
||||
|
||||
npm init "@clusterio" -- --mode host --host-name my-host --controller-url https://example.com/
|
||||
|
||||
The installer runs without prompts when all the questions for the mode are answered with options.
|
||||
|
||||
|
||||
## Modes
|
||||
|
||||
- `standalone`: controller and host on this computer. The host is approved like any other host the first time it starts.
|
||||
- `controller`: controller only.
|
||||
- `host`: host only, joins the cluster of an existing controller, see [Setting up a host](#setting-up-a-host).
|
||||
- `ctl`: the clusterioctl command line interface only.
|
||||
- `plugins`: plugins only, for adding plugins to an existing installation.
|
||||
- `plugin-template`: files for writing a new plugin.
|
||||
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Modes | Description |
|
||||
| --- | --- | --- |
|
||||
| `--mode <mode>` | all | Operating mode to install. |
|
||||
| `--admin <name>` | controller | Name of the admin account to create. |
|
||||
| `--http-port <port>` | controller | Port the controller web interface listens on, defaults to 8080. |
|
||||
| `--host-name <name>` | host | Name to request for the host, defaults to the name of the computer. |
|
||||
| `--controller-url <url>` | host, ctl | URL of the controller, the same as for its web interface. |
|
||||
| `--controller-token <token>` | ctl | Authentication token saved for clusterioctl. |
|
||||
| `--public-address <address>` | host | DNS name or IP address players connect to this computer with. |
|
||||
| `--factorio-dir <path>` | host | Path to the Factorio installation. |
|
||||
| `--self-signed-cert <path>` | host | Certificate to trust for a controller using a self-signed certificate. It is added to the run scripts. |
|
||||
| `--remote-npm`, `--no-remote-npm` | controller, host | Allow or deny remote updates, plugin updates and plugin installs from the web interface. |
|
||||
| `--plugins <package...>` | all | Plugins to install, pass `--plugins` without packages to install none. |
|
||||
| `--plugin-template <template...>`, `--plugin-name <name>` | plugin-template | Templates to use and name of the new plugin. |
|
||||
| `--log-level <level>` | all | Log level to print, defaults to info. |
|
||||
| `--allow-install-as-root` | all | Linux only, allow installing as root (not recommended). |
|
||||
| `--migrate-rename` | | Migrate an installation from before the slave/master rename. |
|
||||
|
||||
Options for the `controller` and `host` modes also work in the `standalone` mode, except for `--controller-url` as the host connects to the controller on the same computer.
|
||||
`--host-name` defaults to `local` in the `standalone` mode.
|
||||
|
||||
|
||||
## Setting up a host
|
||||
|
||||
A new host has to be approved before it can join the cluster:
|
||||
|
||||
1. Run the installer with the host mode on the computer for the host.
|
||||
It asks for a name for the host, the controller URL, the public address, the Factorio installation, whether to allow remote updates and which plugins to install.
|
||||
|
||||
2. Start the host with `run-host.cmd`, `run-host.sh` or the systemd service in the `systemd` folder.
|
||||
The first time it starts it prints a code and waits for the host to be approved:
|
||||
|
||||
Waiting for approval of "my-host" with code ABC-DEF, open this link to approve it:
|
||||
https://example.com/hosts?approve=ABC-DEF
|
||||
Or run: npx clusterioctl host approve ABC-DEF
|
||||
|
||||
3. Open the link to approve the request in the web interface, where its name can be changed first.
|
||||
It can also be approved under Add host on the Hosts page, or with `npx clusterioctl host approve ABC-DEF`.
|
||||
Only approve a request if its code matches the one shown by the host.
|
||||
Approving requires the `core.host.approve` permission.
|
||||
|
||||
4. The host saves `host.id`, `host.name` and `host.controller_token` to `config-host.json` and starts up.
|
||||
Later starts connect to the cluster straight away.
|
||||
|
||||
The host keeps waiting until the request is approved, also if the controller is restarted or can't be reached for a while.
|
||||
Press Ctrl+C to stop waiting.
|
||||
If the request is rejected the host exits with code 8, which the run scripts do not restart on.
|
||||
|
||||
Start the host with `npx clusteriohost run --user-token <token>` and the token of a user that has the `core.host.approve` permission to approve the host without waiting.
|
||||
The token is only used for approving the host and is not saved.
|
||||
|
||||
If the controller uses a self-signed certificate pass it with `--self-signed-cert <path>`, see [setting up TLS](https://github.com/clusterio/clusterio/blob/master/docs/setting-up-tls.md#creating-and-using-a-self-signed-certificate).
|
||||
The installer adds it to the run scripts.
|
||||
|
||||
When a host is revoked in the web interface or with `npx clusterioctl host revoke <host>` its token stops working and a running host shuts down.
|
||||
Starting it again requests to join the cluster again, and the host gets a new id once approved.
|
||||
|
||||
To move a host to another controller, change `host.controller_url` with `npx clusteriohost config set host.controller_url <url>`.
|
||||
The new controller does not accept the token of the host, so the host requests to join it the next time it starts.
|
||||
|
||||
|
||||
## Docker
|
||||
|
||||
To run a host in a container install it when building the image with all answers given as options.
|
||||
The host requests to join the cluster the first time the container starts.
|
||||
|
||||
```dockerfile
|
||||
FROM node:22
|
||||
# Install the Factorio headless server to /opt/factorio here
|
||||
RUN mkdir /clusterio && chown node:node /clusterio
|
||||
USER node
|
||||
WORKDIR /clusterio
|
||||
RUN npm init "@clusterio" -- --mode host --host-name my-host --controller-url https://example.com/ \
|
||||
--public-address factorio.example.com --factorio-dir /opt/factorio --no-remote-npm --plugins
|
||||
VOLUME /clusterio
|
||||
CMD exec ./node_modules/.bin/clusteriohost run ${USER_TOKEN:+--user-token "$USER_TOKEN"}
|
||||
```
|
||||
|
||||
docker run -d --name my-host -v my-host:/clusterio -p 34100-34199:34100-34199/udp my-host-image
|
||||
docker logs my-host
|
||||
|
||||
- The volume holds `config-host.json`, without it every new container requests to join as a new host.
|
||||
Docker copies the installation from the image into a new empty volume, later image updates do not change the installation in an existing volume.
|
||||
- The code to approve is printed to the container log, or set `USER_TOKEN` to approve the host without waiting.
|
||||
- Stop the container after revoking its host, otherwise a restart requests to join again.
|
||||
+188
-203
@@ -1,10 +1,14 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import checkbox from "@inquirer/checkbox";
|
||||
import confirm from "@inquirer/confirm";
|
||||
import input from "@inquirer/input";
|
||||
import select from "@inquirer/select";
|
||||
import child_process from "node:child_process";
|
||||
import fs from "node:fs/promises";
|
||||
import inquirer from "inquirer";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
import readline from "node:readline";
|
||||
import stream from "node:stream";
|
||||
import util from "node:util";
|
||||
import yargs from "yargs";
|
||||
@@ -16,15 +20,13 @@ const scriptExt = process.platform === "win32" ? ".cmd" : "";
|
||||
import { escapeArg } from "./escape_arg.js";
|
||||
|
||||
// I hate this, there is a bug with rl.close on windows that was meant to have been fixed in Node14.4
|
||||
// See nodejs/node#21771 and nodejs/node#30701 for the apparent fix that was applied
|
||||
// One option is to not call rl.close: SBoudrias/Inquirer.js#767
|
||||
// But this comes with its own issues: SBoudrias/Inquirer.js#899
|
||||
// See nodejs/node#21771, nodejs/node#30701 and nodejs/node#31762
|
||||
// The solution below was adapted from aws-amplify/amplify-cli#12347
|
||||
if (process.platform === "win32") {
|
||||
const _inquirer_close = inquirer.ui.Prompt.prototype.close;
|
||||
inquirer.ui.Prompt.prototype.close = function() {
|
||||
this.rl.terminal = false;
|
||||
_inquirer_close.call(this);
|
||||
const close = readline.Interface.prototype.close;
|
||||
readline.Interface.prototype.close = function() {
|
||||
this.terminal = false;
|
||||
close.call(this);
|
||||
};
|
||||
}
|
||||
|
||||
@@ -44,6 +46,10 @@ const factorioLocations = {
|
||||
],
|
||||
darwin: [
|
||||
"/Applications/factorio.app/Contents",
|
||||
path.join(
|
||||
os.homedir(), "Library", "Application Support", "Steam", "steamapps", "common", "Factorio",
|
||||
"factorio.app", "Contents",
|
||||
),
|
||||
],
|
||||
};
|
||||
|
||||
@@ -102,7 +108,7 @@ async function pathExists(filePath) {
|
||||
return true;
|
||||
}
|
||||
|
||||
async function safeOutputFile(file, data, options={}) {
|
||||
async function atomicOverwriteFile(file, data, options={}) {
|
||||
let { dir, name, ext } = path.parse(file);
|
||||
let temporary = path.join(dir, `${name}.tmp${ext}`);
|
||||
if (dir) {
|
||||
@@ -161,21 +167,48 @@ async function execCtl(args) {
|
||||
return await execFile(path.join("node_modules", ".bin", `clusterioctl${scriptExt}`), args);
|
||||
}
|
||||
|
||||
function validateHostToken(token) {
|
||||
let parts = token.split(".");
|
||||
if (parts.length !== 3) {
|
||||
throw new InstallError("Invalid token");
|
||||
}
|
||||
// Same characters as the controller refuses in host names.
|
||||
const hostNameControlCharacters = /[\p{Cc}\u202a-\u202e\u2066-\u2069]/u;
|
||||
|
||||
let parsed;
|
||||
function validateHostName(value) {
|
||||
if (!value || !value.trim()) {
|
||||
return "Host name may not be empty";
|
||||
}
|
||||
if (value.trim().length > 100) {
|
||||
return "Host name may be at most 100 characters";
|
||||
}
|
||||
if (hostNameControlCharacters.test(value)) {
|
||||
return "Host name may not contain control characters";
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function validateControllerUrl(value) {
|
||||
let url;
|
||||
try {
|
||||
parsed = JSON.parse(Buffer.from(parts[1], "base64"));
|
||||
url = new URL(value);
|
||||
} catch (err) {
|
||||
throw new InstallError("Invalid token");
|
||||
return "Controller URL must be a URL like https://example.com/";
|
||||
}
|
||||
if (!["http:", "https:"].includes(url.protocol)) {
|
||||
return "Controller URL must start with http:// or https://";
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
if (parsed.aud !== "host" || !Number.isInteger(parsed.host)) {
|
||||
throw new InstallError("Invalid token");
|
||||
// The host requires the controller URL to end with a slash.
|
||||
function normaliseControllerUrl(value) {
|
||||
const url = new URL(value);
|
||||
if (!url.pathname.endsWith("/")) {
|
||||
url.pathname += "/";
|
||||
}
|
||||
return url.href;
|
||||
}
|
||||
|
||||
// Remote updates, plugin updates and plugin installs are allowed or denied together.
|
||||
async function setRemoteUpdates(exec, component, allow) {
|
||||
for (let field of ["allow_remote_updates", "allow_plugin_updates", "allow_plugin_install"]) {
|
||||
await exec(["config", "set", `${component}.${field}`, allow]);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -228,7 +261,7 @@ async function migrateRename(args) {
|
||||
|
||||
async function migrateConfig(source, destination) {
|
||||
if (await pathExists(source) && !await pathExists(destination)) {
|
||||
await safeOutputFile(destination, JSON.stringify(
|
||||
await atomicOverwriteFile(destination, JSON.stringify(
|
||||
renameConfig(JSON.parse(await fs.readFile(source))), null, "\t"
|
||||
), { mode: 0o600 });
|
||||
logger.info(`Migrated ${source} to ${destination}`);
|
||||
@@ -240,7 +273,7 @@ async function migrateRename(args) {
|
||||
|
||||
let instancesFile = path.join("database", "instances.json");
|
||||
if (await pathExists(instancesFile)) {
|
||||
await safeOutputFile(instancesFile, JSON.stringify(
|
||||
await atomicOverwriteFile(instancesFile, JSON.stringify(
|
||||
JSON.parse(await fs.readFile(instancesFile)).map(renameConfig), null, "\t"
|
||||
));
|
||||
logger.info(`Migrated ${instancesFile}`);
|
||||
@@ -252,7 +285,7 @@ async function migrateRename(args) {
|
||||
for (let role of users["roles"]) {
|
||||
role["permissions"] = role["permissions"].map(rename);
|
||||
}
|
||||
await safeOutputFile(usersFile, JSON.stringify(users, null, "\t"));
|
||||
await atomicOverwriteFile(usersFile, JSON.stringify(users, null, "\t"));
|
||||
logger.info(`Migrated ${usersFile}`);
|
||||
}
|
||||
|
||||
@@ -280,7 +313,7 @@ async function migrateRename(args) {
|
||||
lines.push(inputLine);
|
||||
}
|
||||
}
|
||||
safeOutputFile(outputFile, Buffer.concat(lines));
|
||||
atomicOverwriteFile(outputFile, Buffer.concat(lines));
|
||||
}
|
||||
|
||||
async function migrateLogsDir(inputLogs, outputLogs) {
|
||||
@@ -405,7 +438,7 @@ async function groupIdToName(gid) {
|
||||
async function writeScripts(mode, selfSignedCert) {
|
||||
if (["standalone", "controller"].includes(mode)) {
|
||||
if (process.platform === "win32") {
|
||||
await safeOutputFile(
|
||||
await atomicOverwriteFile(
|
||||
"run-controller.cmd",
|
||||
`\
|
||||
@echo off
|
||||
@@ -413,24 +446,25 @@ set "NODE_OPTIONS=--enable-source-maps %NODE_OPTIONS%"
|
||||
:restart
|
||||
call .\\node_modules\\.bin\\clusteriocontroller.cmd run --can-restart
|
||||
if %errorlevel% equ 0 exit /b
|
||||
if %errorlevel% equ 8 exit /b
|
||||
if %errorlevel% equ 8 exit /b 8
|
||||
goto restart
|
||||
`
|
||||
);
|
||||
} else {
|
||||
await safeOutputFile(
|
||||
await atomicOverwriteFile(
|
||||
"run-controller.sh",
|
||||
`\
|
||||
#!/bin/bash
|
||||
export "NODE_OPTIONS=--enable-source-maps $NODE_OPTIONS"
|
||||
while true; do
|
||||
./node_modules/.bin/clusteriocontroller run --can-restart
|
||||
if [[ $? -eq 0 || $? -eq 8 ]]; then exit $?; fi
|
||||
code=$?
|
||||
if [[ $code -eq 0 || $code -eq 8 ]]; then exit $code; fi
|
||||
done
|
||||
`,
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
await safeOutputFile(
|
||||
await atomicOverwriteFile(
|
||||
"systemd/clusteriocontroller.service",
|
||||
`\
|
||||
[Unit]
|
||||
@@ -457,7 +491,7 @@ WantedBy=multi-user.target
|
||||
if (["standalone", "host"].includes(mode)) {
|
||||
if (process.platform === "win32") {
|
||||
let extraCaCertsLine = selfSignedCert ? `set "NODE_EXTRA_CA_CERTS=${selfSignedCert}"\n` : "";
|
||||
await safeOutputFile(
|
||||
await atomicOverwriteFile(
|
||||
"run-host.cmd",
|
||||
`\
|
||||
@echo off
|
||||
@@ -465,26 +499,27 @@ set "NODE_OPTIONS=--enable-source-maps %NODE_OPTIONS%"
|
||||
${extraCaCertsLine}:restart
|
||||
call .\\node_modules\\.bin\\clusteriohost.cmd run --can-restart
|
||||
if %errorlevel% equ 0 exit /b
|
||||
if %errorlevel% equ 8 exit /b
|
||||
if %errorlevel% equ 8 exit /b 8
|
||||
goto restart
|
||||
`
|
||||
);
|
||||
} else {
|
||||
let extraCaCertsLine = selfSignedCert ? `export "NODE_EXTRA_CA_CERTS=${selfSignedCert}"\n` : "";
|
||||
await safeOutputFile(
|
||||
await atomicOverwriteFile(
|
||||
"run-host.sh",
|
||||
`\
|
||||
#!/bin/bash
|
||||
export "NODE_OPTIONS=--enable-source-maps $NODE_OPTIONS"
|
||||
${extraCaCertsLine}while true; do
|
||||
./node_modules/.bin/clusteriohost run --can-restart
|
||||
if [[ $? -eq 0 || $? -eq 8 ]]; then exit $?; fi
|
||||
code=$?
|
||||
if [[ $code -eq 0 || $code -eq 8 ]]; then exit $code; fi
|
||||
done
|
||||
`,
|
||||
{ mode: 0o755 },
|
||||
);
|
||||
extraCaCertsLine = selfSignedCert ? `Environment=NODE_EXTRA_CA_CERTS=${selfSignedCert}\n` : "";
|
||||
await safeOutputFile(
|
||||
await atomicOverwriteFile(
|
||||
"systemd/clusteriohost.service",
|
||||
`\
|
||||
[Unit]
|
||||
@@ -510,96 +545,87 @@ WantedBy=multi-user.target
|
||||
}
|
||||
|
||||
// eslint-disable-next-line complexity
|
||||
async function inquirerMissingArgs(args) {
|
||||
async function promptMissingArgs(args) {
|
||||
let answers = {};
|
||||
if (args.mode) { answers.mode = args.mode; }
|
||||
if (args["plugin-template"]) { answers.mode = "plugin-template"; }
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "list",
|
||||
name: "mode",
|
||||
message: "Operating mode to install",
|
||||
default: "standalone",
|
||||
choices: [
|
||||
{ name: "Standalone (install both controller and host on this computer)", value: "standalone" },
|
||||
{ name: "Controller only", value: "controller" },
|
||||
{ name: "Host only", value: "host" },
|
||||
{ name: "Ctl only", value: "ctl" },
|
||||
{ name: "Plugins only", value: "plugins" },
|
||||
{ name: "Plugin template", value: "plugin-template" },
|
||||
],
|
||||
},
|
||||
], answers);
|
||||
answers.mode ??= await select({
|
||||
message: "Operating mode to install",
|
||||
default: "standalone",
|
||||
choices: [
|
||||
{ name: "Standalone (install both controller and host on this computer)", value: "standalone" },
|
||||
{ name: "Controller only", value: "controller" },
|
||||
{ name: "Host only", value: "host" },
|
||||
{ name: "Ctl only", value: "ctl" },
|
||||
{ name: "Plugins only", value: "plugins" },
|
||||
{ name: "Plugin template", value: "plugin-template" },
|
||||
],
|
||||
});
|
||||
|
||||
if (["standalone", "controller"].includes(answers.mode)) {
|
||||
if (args.admin) { answers.admin = args.admin; }
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "input",
|
||||
name: "admin",
|
||||
message: "Admin account name",
|
||||
validate: input => {
|
||||
if (!input) {
|
||||
return "May not be empty";
|
||||
}
|
||||
return true;
|
||||
},
|
||||
answers.admin ??= await input({
|
||||
message: "Admin account name",
|
||||
validate: value => {
|
||||
if (!value) {
|
||||
return "May not be empty";
|
||||
}
|
||||
return true;
|
||||
},
|
||||
], answers);
|
||||
});
|
||||
|
||||
if (args.httpPort) { answers.httpPort = args.httpPort; }
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "input",
|
||||
name: "httpPort",
|
||||
message: "HTTP port to listen on",
|
||||
default: 8080,
|
||||
validate: input => {
|
||||
if (!input) {
|
||||
return "May not be empty";
|
||||
}
|
||||
if (!Number.isInteger(Number(input))) {
|
||||
return "Must be a number";
|
||||
}
|
||||
return true;
|
||||
},
|
||||
answers.httpPort ??= await input({
|
||||
message: "HTTP port to listen on",
|
||||
default: "8080",
|
||||
validate: value => {
|
||||
if (!value) {
|
||||
return "May not be empty";
|
||||
}
|
||||
if (!Number.isInteger(Number(value))) {
|
||||
return "Must be a number";
|
||||
}
|
||||
return true;
|
||||
},
|
||||
], answers);
|
||||
});
|
||||
}
|
||||
|
||||
if (answers.mode === "standalone") {
|
||||
answers.hostName = args.hostName ?? "local";
|
||||
const result = validateHostName(answers.hostName);
|
||||
if (result !== true) {
|
||||
throw new InstallError(result);
|
||||
}
|
||||
}
|
||||
|
||||
if (answers.mode === "host") {
|
||||
if (args.hostName) { answers.hostName = args.hostName; }
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "input",
|
||||
name: "hostName",
|
||||
message: "Name of host",
|
||||
},
|
||||
], answers);
|
||||
if (args.controllerUrl) { answers.controllerUrl = args.controllerUrl; }
|
||||
answers.hostName ??= await input({
|
||||
message: "Name of host",
|
||||
default: os.hostname(),
|
||||
validate: validateHostName,
|
||||
});
|
||||
answers.controllerUrl ??= await input({
|
||||
message: "Controller URL",
|
||||
validate: validateControllerUrl,
|
||||
});
|
||||
|
||||
// The prompts do not validate answers given as arguments
|
||||
for (let result of [validateHostName(answers.hostName), validateControllerUrl(answers.controllerUrl)]) {
|
||||
if (result !== true) {
|
||||
throw new InstallError(result);
|
||||
}
|
||||
}
|
||||
answers.controllerUrl = normaliseControllerUrl(answers.controllerUrl);
|
||||
}
|
||||
|
||||
if (["host", "ctl"].includes(answers.mode)) {
|
||||
if (answers.mode === "ctl") {
|
||||
if (args.controllerUrl) { answers.controllerUrl = args.controllerUrl; }
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "input",
|
||||
name: "controllerUrl",
|
||||
message: "Controller URL",
|
||||
},
|
||||
], answers);
|
||||
answers.controllerUrl ??= await input({ message: "Controller URL" });
|
||||
|
||||
if (args.controllerToken) { answers.controllerToken = args.controllerToken; }
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "input",
|
||||
name: "controllerToken",
|
||||
message: "Controller authentication Token",
|
||||
},
|
||||
], answers);
|
||||
}
|
||||
|
||||
if (answers.mode === "host") {
|
||||
validateHostToken(answers.controllerToken);
|
||||
answers.controllerToken ??= await input({ message: "Controller authentication Token" });
|
||||
}
|
||||
|
||||
if (["standalone", "host"].includes(answers.mode)) {
|
||||
@@ -612,14 +638,10 @@ async function inquirerMissingArgs(args) {
|
||||
myIp = await result.text();
|
||||
} catch (err) { /* ignore */ }
|
||||
}
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "input",
|
||||
name: "publicAddress",
|
||||
message: "Public DNS/IP address of this server",
|
||||
default: myIp,
|
||||
},
|
||||
], answers);
|
||||
answers.publicAddress ??= await input({
|
||||
message: "Public DNS/IP address of this server",
|
||||
default: myIp,
|
||||
});
|
||||
|
||||
if (args.factorioDir) { answers.factorioDir = args.factorioDir; }
|
||||
let locations = factorioLocations[process.platform] || [];
|
||||
@@ -630,28 +652,17 @@ async function inquirerMissingArgs(args) {
|
||||
}
|
||||
}
|
||||
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "list",
|
||||
name: "factorioDir",
|
||||
message: "Path to Factorio installation",
|
||||
choices: [
|
||||
...foundLocations.map(location => ({ name: `${location} (auto detected)`, value: location })),
|
||||
{ name: "Use local factorio directory, you must copy an installation to it", value: "factorio" },
|
||||
{ name: "Provide path manually", value: null },
|
||||
],
|
||||
},
|
||||
], answers);
|
||||
answers.factorioDir ??= await select({
|
||||
message: "Path to Factorio installation",
|
||||
choices: [
|
||||
...foundLocations.map(location => ({ name: `${location} (auto detected)`, value: location })),
|
||||
{ name: "Use local factorio directory, you must copy an installation to it", value: "factorio" },
|
||||
{ name: "Provide path manually", value: null },
|
||||
],
|
||||
});
|
||||
|
||||
if (answers.factorioDir === null) {
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "input",
|
||||
name: "factorioDir",
|
||||
message: "Path to Factorio installation",
|
||||
askAnswered: true,
|
||||
},
|
||||
], answers);
|
||||
answers.factorioDir = await input({ message: "Path to Factorio installation" });
|
||||
} else if (answers.factorioDir === "factorio") {
|
||||
await fs.mkdir("factorio", { recursive: true });
|
||||
}
|
||||
@@ -659,14 +670,10 @@ async function inquirerMissingArgs(args) {
|
||||
|
||||
if (["standalone", "controller", "host"].includes(answers.mode)) {
|
||||
if (args.hasOwnProperty("remoteNpm")) { answers.remoteNpm = args.remoteNpm; }
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "confirm",
|
||||
name: "remoteNpm",
|
||||
message: "Allow remote updates via npm?",
|
||||
default: true,
|
||||
},
|
||||
], answers);
|
||||
answers.remoteNpm ??= await confirm({
|
||||
message: "Allow remote updates and plugin installs from the web interface?",
|
||||
default: true,
|
||||
});
|
||||
}
|
||||
|
||||
if (answers.mode === "plugin-template") {
|
||||
@@ -677,29 +684,23 @@ async function inquirerMissingArgs(args) {
|
||||
answers.pluginName = args["plugin-name"];
|
||||
}
|
||||
answers.plugins = [];
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "checkbox",
|
||||
name: "pluginTemplate",
|
||||
message: "Plugin templates to use",
|
||||
choices: [
|
||||
{ name: "Controller", value: "controller" },
|
||||
{ name: "Host", value: "host" },
|
||||
{ name: "Instance", value: "instance" },
|
||||
{ name: "Lua Module", value: "module" },
|
||||
{ name: "Command Line", value: "ctl" },
|
||||
{ name: "Web UI", value: "web" },
|
||||
{ name: "No Typescript", value: "js" },
|
||||
{ name: "No Config", value: "no_config" },
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "input",
|
||||
name: "pluginName",
|
||||
message: "Name of your new plugin",
|
||||
default: path.basename(path.resolve()),
|
||||
},
|
||||
], answers);
|
||||
answers.pluginTemplate ??= await checkbox({
|
||||
message: "Plugin templates to use",
|
||||
choices: [
|
||||
{ name: "Controller", value: "controller" },
|
||||
{ name: "Host", value: "host" },
|
||||
{ name: "Instance", value: "instance" },
|
||||
{ name: "Lua Module", value: "module" },
|
||||
{ name: "Command Line", value: "ctl" },
|
||||
{ name: "Web UI", value: "web" },
|
||||
{ name: "No Typescript", value: "js" },
|
||||
{ name: "No Config", value: "no_config" },
|
||||
],
|
||||
});
|
||||
answers.pluginName ??= await input({
|
||||
message: "Name of your new plugin",
|
||||
default: path.basename(path.resolve()),
|
||||
});
|
||||
}
|
||||
|
||||
if (dev) {
|
||||
@@ -707,15 +708,11 @@ async function inquirerMissingArgs(args) {
|
||||
} else if (args.plugins) {
|
||||
answers.plugins = args.plugins;
|
||||
}
|
||||
answers = await inquirer.prompt([
|
||||
{
|
||||
type: "checkbox",
|
||||
name: "plugins",
|
||||
message: "Plugins to install",
|
||||
choices: availablePlugins,
|
||||
pageSize: 20,
|
||||
},
|
||||
], answers);
|
||||
answers.plugins ??= await checkbox({
|
||||
message: "Plugins to install",
|
||||
choices: availablePlugins,
|
||||
pageSize: 20,
|
||||
});
|
||||
|
||||
return answers;
|
||||
}
|
||||
@@ -743,13 +740,13 @@ async function main() {
|
||||
nargs: 1, describe: "HTTP port to listen on [standalone/controller]", type: "number",
|
||||
})
|
||||
.option("host-name", {
|
||||
nargs: 1, describe: "Host name [host]", type: "string",
|
||||
nargs: 1, describe: "Host name [standalone/host]", type: "string",
|
||||
})
|
||||
.option("controller-url", {
|
||||
nargs: 1, describe: "Controller URL [host/ctl]", type: "string",
|
||||
})
|
||||
.option("controller-token", {
|
||||
nargs: 1, describe: "Controller authentication token [host/ctl]", type: "string",
|
||||
nargs: 1, describe: "Controller authentication token [ctl]", type: "string",
|
||||
})
|
||||
.option("public-address", {
|
||||
nargs: 1, describe: "DNS/IP Address to connect to this server [standalone/host]", type: "string",
|
||||
@@ -761,7 +758,8 @@ async function main() {
|
||||
nargs: 1, describe: "Path to self-signed certificate of the controller [standalone/host]", type: "string",
|
||||
})
|
||||
.option("remote-npm", {
|
||||
nargs: 0, description: "Allow remote updates via npm [standalone/controller/host]", type: "boolean",
|
||||
nargs: 0, type: "boolean", description:
|
||||
"Allow remote updates and plugin installs from the web interface [standalone/controller/host]",
|
||||
})
|
||||
.option("plugins", {
|
||||
array: true, describe: "Plugins to install", type: "string",
|
||||
@@ -798,7 +796,7 @@ async function main() {
|
||||
return;
|
||||
}
|
||||
|
||||
let answers = await inquirerMissingArgs(args);
|
||||
let answers = await promptMissingArgs(args);
|
||||
logger.verbose(JSON.stringify(answers));
|
||||
|
||||
if (answers.pluginTemplate) {
|
||||
@@ -816,44 +814,28 @@ async function main() {
|
||||
await execController(["config", "create"]);
|
||||
await execController(["bootstrap", "create-admin", answers.admin]);
|
||||
await execController(["config", "set", "controller.http_port", answers.httpPort]);
|
||||
await execController(["config", "set", "controller.allow_remote_updates", answers.remoteNpm]);
|
||||
await execController(["config", "set", "controller.allow_plugin_updates", answers.remoteNpm]);
|
||||
await setRemoteUpdates(execController, "controller", answers.remoteNpm);
|
||||
let result = await execController(["bootstrap", "generate-user-token", answers.admin]);
|
||||
adminToken = result.stdout.split("\n").slice(-2)[0];
|
||||
}
|
||||
|
||||
if (answers.mode === "standalone") {
|
||||
if (["standalone", "host"].includes(answers.mode)) {
|
||||
logger.info("Setting up host");
|
||||
await execHost(["config", "create"]);
|
||||
await execHost(["config", "set", "host.name", "local"]);
|
||||
|
||||
let result = await execHost(["config", "show", "host.id"]);
|
||||
let hostId = Number.parseInt(result.stdout.split("\n").slice(-2)[0], 10);
|
||||
|
||||
result = await execController(["bootstrap", "generate-host-token", hostId]);
|
||||
let hostToken = result.stdout.split("\n").slice(-2)[0];
|
||||
|
||||
// Default to localhost on correct port for host in standalone mode
|
||||
await execHost(["config", "set", "host.controller_url", `http://localhost:${answers.httpPort}/`]);
|
||||
await execHost(["config", "set", "host.controller_token", hostToken]);
|
||||
await execHost(["config", "set", "host.public_address", answers.publicAddress]);
|
||||
await execHost(["config", "set", "host.factorio_directory", answers.factorioDir]);
|
||||
await execHost(["config", "set", "host.allow_remote_updates", answers.remoteNpm]);
|
||||
await execHost(["config", "set", "host.allow_plugin_updates", answers.remoteNpm]);
|
||||
}
|
||||
|
||||
if (answers.mode === "host") {
|
||||
logger.info("Setting up host");
|
||||
let hostId = JSON.parse(Buffer.from(answers.controllerToken.split(".")[1], "base64")).host;
|
||||
await execHost(["config", "create"]);
|
||||
await execHost(["config", "set", "host.id", hostId]);
|
||||
if (answers.mode === "standalone") {
|
||||
// Default to localhost on correct port for host in standalone mode
|
||||
answers.controllerUrl = `http://localhost:${answers.httpPort}/`;
|
||||
}
|
||||
|
||||
if (["standalone", "host"].includes(answers.mode)) {
|
||||
// The host requests to join the cluster when it is started.
|
||||
await execHost(["config", "set", "host.name", answers.hostName]);
|
||||
await execHost(["config", "set", "host.controller_url", answers.controllerUrl]);
|
||||
await execHost(["config", "set", "host.controller_token", answers.controllerToken]);
|
||||
await execHost(["config", "set", "host.public_address", answers.publicAddress]);
|
||||
await execHost(["config", "set", "host.factorio_directory", answers.factorioDir]);
|
||||
await execHost(["config", "set", "host.allow_remote_updates", answers.remoteNpm]);
|
||||
await execHost(["config", "set", "host.allow_plugin_updates", answers.remoteNpm]);
|
||||
await setRemoteUpdates(execHost, "host", answers.remoteNpm);
|
||||
}
|
||||
|
||||
if (!dev && ["standalone", "controller", "host"].includes(answers.mode)) {
|
||||
@@ -878,7 +860,10 @@ async function main() {
|
||||
if (import.meta.main) {
|
||||
main().catch(err => {
|
||||
process.exitCode = 1;
|
||||
if (err instanceof InstallError) {
|
||||
if (err.name === "ExitPromptError") {
|
||||
// Ctrl+C at a prompt
|
||||
process.exitCode = 130;
|
||||
} else if (err instanceof InstallError) {
|
||||
logger.error(err.message);
|
||||
} else {
|
||||
logger.fatal(`
|
||||
|
||||
@@ -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,6 +1,6 @@
|
||||
{
|
||||
"name": "@clusterio/create",
|
||||
"version": "2.0.3",
|
||||
"version": "2.1.2",
|
||||
"description": "Installer for clusterio",
|
||||
"homepage": "https://github.com/clusterio/clusterio#readme",
|
||||
"author": "Hornwitser <github@hornwitser.no>",
|
||||
@@ -28,12 +28,14 @@
|
||||
"clusteriocreate": "./create.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
"node": "^22.18.0 || >=24.2.0"
|
||||
},
|
||||
|
||||
"dependencies": {
|
||||
"chalk": "catalog:",
|
||||
"inquirer": "^8.2.7",
|
||||
"@inquirer/checkbox": "^5.2.8",
|
||||
"@inquirer/confirm": "^6.3.5",
|
||||
"@inquirer/input": "^5.1.9",
|
||||
"@inquirer/select": "^5.2.8",
|
||||
"yargs": "catalog:"
|
||||
}
|
||||
}
|
||||
@@ -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
|
||||
@@ -23,6 +23,11 @@ Common options:
|
||||
* `--create-config` If the config file is missing, create a new one and carry on instead of exiting with an error.
|
||||
Alternative to the `config create` command.
|
||||
|
||||
* `--output <human|json|wire>` Format to print the results of cluster commands in.
|
||||
Defaults to `human`.
|
||||
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.
|
||||
|
||||
|
||||
### `plugin <command>`
|
||||
|
||||
@@ -107,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.
|
||||
+67
-29
@@ -17,6 +17,7 @@ import { ConsoleTransport, levels, logger } from "@clusterio/lib";
|
||||
|
||||
import * as commands from "./src/commands.js";
|
||||
import { BaseCtlPlugin, CtlHooks } from "./src/BaseCtlPlugin.js";
|
||||
import { CommandOutput, errorToJson, outputFormats, print, type OutputFormat } from "./src/command_ops.js";
|
||||
|
||||
|
||||
/**
|
||||
@@ -55,6 +56,8 @@ export class Ctl extends lib.Link {
|
||||
config: lib.CtlConfig;
|
||||
/** Keep the control connection alive after the command completes. */
|
||||
keepOpen = false;
|
||||
/** Output of the command being run. */
|
||||
output = new CommandOutput();
|
||||
|
||||
constructor(
|
||||
connector: CtlConnector,
|
||||
@@ -82,12 +85,20 @@ export class Ctl extends lib.Link {
|
||||
}
|
||||
|
||||
async handleLogMessageEvent(event: lib.LogMessageEvent) {
|
||||
logger.log(event.info as any);
|
||||
// Only log following commands print log events as results, the rest log them to stderr
|
||||
if (this.output.streamingLog) {
|
||||
this.output.result(event.info, () => logger.log(event.info as any));
|
||||
} else {
|
||||
logger.log(event.info as any);
|
||||
}
|
||||
}
|
||||
|
||||
async handleDebugWsMessageEvent(event: lib.DebugWsMessageEvent) {
|
||||
// eslint-disable-next-line no-console
|
||||
console.log("WS", event.direction, event.content);
|
||||
this.output.result(
|
||||
{ direction: event.direction, content: event.content },
|
||||
// eslint-disable-next-line no-console
|
||||
() => console.log("WS", event.direction, event.content),
|
||||
);
|
||||
}
|
||||
|
||||
async shutdown() {
|
||||
@@ -107,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 {
|
||||
@@ -126,6 +135,7 @@ interface CtlArguments {
|
||||
$0: string,
|
||||
_: (string | number)[],
|
||||
logLevel: keyof typeof levels,
|
||||
output: OutputFormat,
|
||||
config: string,
|
||||
pluginList: string,
|
||||
bypassLockFile: boolean,
|
||||
@@ -165,6 +175,13 @@ export async function initialize(
|
||||
choices: Object.keys(levels),
|
||||
type: "string",
|
||||
})
|
||||
.option("output", {
|
||||
nargs: 1,
|
||||
describe: "Format to print command results in",
|
||||
default: "human",
|
||||
choices: outputFormats,
|
||||
type: "string",
|
||||
})
|
||||
.option("config", {
|
||||
nargs: 1,
|
||||
describe: "config file to get credentails from",
|
||||
@@ -260,6 +277,20 @@ export function selectTargetCommand(args: CtlArguments, rootCommands: lib.Comman
|
||||
return targetCommand;
|
||||
}
|
||||
|
||||
/**
|
||||
* Run the command selected by args, printing results in the format given by args.output
|
||||
*/
|
||||
export async function runCommand(
|
||||
args: CtlArguments,
|
||||
rootCommands: lib.CommandTree,
|
||||
link: lib.Link & { output?: CommandOutput },
|
||||
) {
|
||||
link.output = new CommandOutput(args.output);
|
||||
const targetCommand = selectTargetCommand(args, rootCommands);
|
||||
await targetCommand.run(args, link);
|
||||
link.output.finish();
|
||||
}
|
||||
|
||||
async function startCtl() {
|
||||
const {
|
||||
args,
|
||||
@@ -271,10 +302,19 @@ async function startCtl() {
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
await connectAndRun(args, rootCommands, ctlConfig);
|
||||
} catch (err) {
|
||||
if (args.output !== "human") {
|
||||
print(JSON.stringify(errorToJson(err)));
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
async function connectAndRun(args: CtlArguments, rootCommands: lib.CommandTree, ctlConfig: lib.CtlConfig) {
|
||||
if (!ctlConfig.get("ctl.controller_url") || !ctlConfig.get("ctl.controller_token")) {
|
||||
logger.error("Missing URL and/or token to connect with. See README.md for setting up access.");
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
throw new lib.StartupError("Missing URL and/or token to connect with. See README.md for setting up access.");
|
||||
}
|
||||
|
||||
let controlConnector = new CtlConnector(
|
||||
@@ -298,26 +338,25 @@ async function startCtl() {
|
||||
process.on("SIGTERM", lib.createShutdownGuard(logger, "termination", ctl.shutdown.bind(ctl)));
|
||||
|
||||
try {
|
||||
const targetCommand = selectTargetCommand(args, rootCommands);
|
||||
await targetCommand.run(args, ctl);
|
||||
await runCommand(args, rootCommands, ctl);
|
||||
|
||||
} catch (err) {
|
||||
ctl.keepOpen = false;
|
||||
let message: string;
|
||||
if (err instanceof lib.CommandError) {
|
||||
logger.error(`Error running command: ${err.message}`);
|
||||
process.exitCode = 1;
|
||||
message = `Error running command: ${err.message}`;
|
||||
|
||||
} else if (err instanceof lib.ClientError || err instanceof lib.UnavailableError) {
|
||||
logger.error(`Error sending request: ${err.message}`);
|
||||
process.exitCode = 1;
|
||||
message = `Error sending request: ${err.message}`;
|
||||
|
||||
} else if (err instanceof lib.ServerError) {
|
||||
logger.error(`Error sending request:\n${err.stack ?? err.message}`);
|
||||
process.exitCode = 1;
|
||||
message = `Error sending request:\n${err.stack ?? err.message}`;
|
||||
|
||||
} else {
|
||||
throw err;
|
||||
}
|
||||
ctl.output.error(err, () => logger.error(message));
|
||||
process.exitCode = 1;
|
||||
|
||||
} finally {
|
||||
if (!ctl.keepOpen) {
|
||||
@@ -328,6 +367,7 @@ async function startCtl() {
|
||||
|
||||
export function bootstrap() {
|
||||
startCtl().catch(err => {
|
||||
process.exitCode = 1;
|
||||
if (err.errors) {
|
||||
logger.fatal(JSON.stringify(err.errors, null, "\t"));
|
||||
}
|
||||
@@ -340,15 +380,13 @@ export function bootstrap() {
|
||||
${err.stack}`
|
||||
);
|
||||
} else {
|
||||
logger.error(`
|
||||
logger.fatal(`
|
||||
+---------------------------------+
|
||||
| Unable to to start clusterioctl |
|
||||
+---------------------------------+
|
||||
${err.stack}`
|
||||
);
|
||||
}
|
||||
|
||||
process.exitCode = 1;
|
||||
});
|
||||
}
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { bootstrap } from "./ctl.js";
|
||||
export * from "./ctl.js";
|
||||
export { CommandOutput, type OutputFormat } from "./src/command_ops.js";
|
||||
export { BaseCtlPlugin, CtlHooks, type CtlPluginContext } from "./src/BaseCtlPlugin.js";
|
||||
|
||||
if (import.meta.main) {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@clusterio/ctl",
|
||||
"version": "2.0.3",
|
||||
"version": "2.1.2",
|
||||
"description": "Clusterio command line management tool",
|
||||
"homepage": "https://github.com/clusterio/clusterio#readme",
|
||||
"author": "Hornwitser <github@hornwitser.no>",
|
||||
@@ -32,7 +32,7 @@
|
||||
"clusterioctl": "./dist/node/ctl.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
"node": "^22.18.0 || >=24.2.0"
|
||||
},
|
||||
|
||||
"dependencies": {
|
||||
|
||||
@@ -1,4 +1,132 @@
|
||||
import asTableModule from "as-table";
|
||||
|
||||
export function print(...content: any) {
|
||||
// eslint-disable-next-line no-console
|
||||
console.log(...content);
|
||||
}
|
||||
|
||||
function formatCell(value: unknown) {
|
||||
if (value instanceof Set) {
|
||||
return [...value].join(", ");
|
||||
}
|
||||
return String(value);
|
||||
}
|
||||
|
||||
export const asTable = asTableModule.configure({ delimiter: " | ", print: formatCell });
|
||||
|
||||
/** Copy of object with only the given fields, or all of them if fields includes "all" */
|
||||
export function pickFields(object: object, fields: string[]) {
|
||||
if (fields.includes("all")) {
|
||||
return object;
|
||||
}
|
||||
return Object.fromEntries(Object.entries(object).filter(([field]) => fields.includes(field)));
|
||||
}
|
||||
|
||||
/** Convert class instances, Sets and Maps into plain JSON values, ignoring wire format toJSON methods */
|
||||
export function toPlain(value: unknown): unknown {
|
||||
if (value instanceof Set || value instanceof Array) {
|
||||
return [...value].map(toPlain);
|
||||
}
|
||||
if (value instanceof Map) {
|
||||
return Object.fromEntries([...value].map(([key, entry]) => [key, toPlain(entry)]));
|
||||
}
|
||||
if (value instanceof Date) {
|
||||
return value.toISOString();
|
||||
}
|
||||
if (typeof value === "object" && value !== null) {
|
||||
return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, toPlain(entry)]));
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
/** Describe an error as `{ error: ClassName, message: string }` */
|
||||
export function errorToJson(err: unknown) {
|
||||
if (err instanceof Error) {
|
||||
return { error: err.constructor.name, message: err.message };
|
||||
}
|
||||
return { error: "Error", message: String(err) };
|
||||
}
|
||||
|
||||
/** JSON.stringify replacer for Sets and Maps that have no toJSON method */
|
||||
function wireReplacer(key: string, value: unknown) {
|
||||
if (value instanceof Set) {
|
||||
return [...value];
|
||||
}
|
||||
if (value instanceof Map) {
|
||||
return Object.fromEntries(value);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
export const outputFormats = ["human", "json", "wire"] as const;
|
||||
export type OutputFormat = typeof outputFormats[number];
|
||||
|
||||
/**
|
||||
* Prints the results of a ctl command in the format chosen with --output
|
||||
*
|
||||
* In json and wire mode each call to result prints one line of JSON to stdout. json uses the
|
||||
* property names of the objects, wire uses their toJSON methods to give the format sent over the link.
|
||||
*/
|
||||
export class CommandOutput {
|
||||
/** True once a result has been printed */
|
||||
written = false;
|
||||
/** Command prints log events as results while it runs and has no final result */
|
||||
streamingLog = false;
|
||||
|
||||
constructor(
|
||||
public format: OutputFormat = "human",
|
||||
) { }
|
||||
|
||||
get human() {
|
||||
return this.format === "human";
|
||||
}
|
||||
|
||||
/**
|
||||
* Print the result of a command
|
||||
*
|
||||
* @param data - Printed as JSON in json and wire mode.
|
||||
* @param human - Prints the result in human mode, defaults to printing data as is.
|
||||
*/
|
||||
result(data: unknown, human: () => void = () => print(data)) {
|
||||
this.written = true;
|
||||
if (this.format === "json") {
|
||||
print(JSON.stringify(toPlain(data)));
|
||||
} else if (this.format === "wire") {
|
||||
print(JSON.stringify(data, wireReplacer));
|
||||
} else {
|
||||
human();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Print a list of objects as a table, or as an array in json and wire mode
|
||||
*
|
||||
* @param rows - Printed as is in json and wire mode.
|
||||
* @param map - Converts each row into the table row printed in human mode.
|
||||
*/
|
||||
table<T extends object>(rows: T[], map: (row: T) => object = row => row) {
|
||||
this.result(rows, () => print(asTable(rows.map(map))));
|
||||
}
|
||||
|
||||
/**
|
||||
* Print an error as `{ "error": ClassName, "message": string }` in json and wire mode
|
||||
*
|
||||
* @param err - Error to print.
|
||||
* @param human - Reports the error in human mode.
|
||||
*/
|
||||
error(err: unknown, human: () => void) {
|
||||
this.written = true;
|
||||
if (this.human) {
|
||||
human();
|
||||
} else {
|
||||
print(JSON.stringify(errorToJson(err)));
|
||||
}
|
||||
}
|
||||
|
||||
/** Print a success result for commands that finished without printing one */
|
||||
finish() {
|
||||
if (!this.written && !this.streamingLog) {
|
||||
this.result({ success: true }, () => print("Command ran successfully"));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,15 +1,15 @@
|
||||
import fs from "node:fs/promises";
|
||||
import asTableModule from "as-table";
|
||||
import events from "events";
|
||||
import os from "os";
|
||||
import child_process from "child_process";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
import { asTable, print } from "./command_ops.js";
|
||||
import {
|
||||
serializedConfigToString, getEditor, configToKeyVal, printConfig, printRestartRequired,
|
||||
} from "./config_ops.js";
|
||||
|
||||
export const controllerCommands = new lib.CommandTree({ name: "controller", description: "Controller management" });
|
||||
controllerCommands.add(new lib.Command({
|
||||
@@ -44,9 +44,8 @@ controllerCommands.add(new lib.Command({
|
||||
}
|
||||
if (args.restart) {
|
||||
await ctl.send(new lib.ControllerRestartRequest());
|
||||
} else {
|
||||
print("Controller updated; a restart is required to apply the changes.");
|
||||
}
|
||||
printRestartRequired(ctl, !args.restart, "Controller updated");
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -57,11 +56,7 @@ const controllerConfigCommands = new lib.CommandTree({
|
||||
controllerConfigCommands.add(new lib.Command({
|
||||
definition: ["list", "List controller configuration"],
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
let config = await ctl.send(new lib.ControllerConfigGetRequest());
|
||||
|
||||
for (let [name, value] of Object.entries(config)) {
|
||||
print(`${name} ${JSON.stringify(value)}`);
|
||||
}
|
||||
printConfig(ctl, await ctl.send(new lib.ControllerConfigGetRequest()));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -146,19 +141,22 @@ controllerConfigCommands.add(new lib.Command({
|
||||
index,
|
||||
final[index],
|
||||
));
|
||||
} catch (err) {
|
||||
// eslint-disable-next-line
|
||||
print(`Attempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`);
|
||||
print(err);
|
||||
} catch (err: any) {
|
||||
// If the string is empty, it's better to just print "" instead of nothing
|
||||
logger.error(
|
||||
`Attempt to set ${index} to ${final[index] || String(null)} failed; ` +
|
||||
`set back to previous value: ${err.message}`
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
try {
|
||||
await fs.unlink(tmpFile);
|
||||
} catch (err) {
|
||||
print("err: temporary file", tmpFile, "could not be deleted.");
|
||||
print("This is not fatal, but they may build up over time if the issue persists.");
|
||||
logger.warn(
|
||||
`Temporary file ${tmpFile} could not be deleted. ` +
|
||||
"This is not fatal, but they may build up over time if the issue persists."
|
||||
);
|
||||
}
|
||||
},
|
||||
}));
|
||||
@@ -175,7 +173,7 @@ controllerPluginCommands.add(new lib.Command({
|
||||
let url = new URL(ctl.config.get("ctl.controller_url")!);
|
||||
url.pathname += "api/plugins";
|
||||
let response = await fetch(url);
|
||||
print(asTable(await response.json() as []));
|
||||
ctl.output.table(await response.json() as object[]);
|
||||
},
|
||||
}));
|
||||
controllerPluginCommands.add(new lib.Command({
|
||||
@@ -187,9 +185,8 @@ controllerPluginCommands.add(new lib.Command({
|
||||
await ctl.sendTo("controller", new lib.PluginUpdateRequest(args.plugin));
|
||||
if (args.restart) {
|
||||
await ctl.send(new lib.ControllerRestartRequest());
|
||||
} else {
|
||||
print("Plugin updated; a restart is required to apply the changes.");
|
||||
}
|
||||
printRestartRequired(ctl, !args.restart, "Plugin updated");
|
||||
},
|
||||
}));
|
||||
controllerPluginCommands.add(new lib.Command({
|
||||
@@ -202,13 +199,16 @@ controllerPluginCommands.add(new lib.Command({
|
||||
const response = await ctl.sendTo(
|
||||
"controller", new lib.PluginSearchRequest(args.query, args.page, args.pageSize)
|
||||
);
|
||||
print(asTable(response.results.map(plugin => ({
|
||||
const results = response.results.map(plugin => ({
|
||||
name: plugin.name,
|
||||
version: plugin.version,
|
||||
publisher: plugin.publisher ?? "",
|
||||
description: plugin.description ?? "",
|
||||
}))));
|
||||
print(`Showing ${response.results.length} of ${response.total} results`);
|
||||
}));
|
||||
ctl.output.result({ total: response.total, results }, () => {
|
||||
print(asTable(results));
|
||||
print(`Showing ${results.length} of ${response.total} results`);
|
||||
});
|
||||
},
|
||||
}));
|
||||
controllerPluginCommands.add(new lib.Command({
|
||||
@@ -220,9 +220,8 @@ controllerPluginCommands.add(new lib.Command({
|
||||
await ctl.sendTo("controller", new lib.PluginInstallRequest(args.plugin));
|
||||
if (args.restart) {
|
||||
await ctl.send(new lib.ControllerRestartRequest());
|
||||
} else {
|
||||
print("Plugin installed; a restart is required to apply the changes.");
|
||||
}
|
||||
printRestartRequired(ctl, !args.restart, "Plugin installed");
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import * as lib from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
|
||||
export const debugCommands = new lib.CommandTree({ name: "debug", description: "Debugging utilities" });
|
||||
debugCommands.add(new lib.Command({
|
||||
@@ -7,6 +8,7 @@ debugCommands.add(new lib.Command({
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
await ctl.send(new lib.DebugDumpWsRequest());
|
||||
ctl.keepOpen = true;
|
||||
ctl.output.streamingLog = true;
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -20,12 +22,6 @@ debugCommands.add(new lib.Command({
|
||||
}],
|
||||
handler: async function(args: { exchangeString: string, pretty: boolean }, ctl: Ctl) {
|
||||
const result = lib.readMapExchangeString(args.exchangeString);
|
||||
if (args.pretty) {
|
||||
// eslint-disable-next-line no-console
|
||||
console.log(JSON.stringify(result, null, 2));
|
||||
} else {
|
||||
// eslint-disable-next-line no-console
|
||||
console.log(JSON.stringify(result));
|
||||
}
|
||||
ctl.output.result(result, () => print(JSON.stringify(result, null, args.pretty ? 2 : undefined)));
|
||||
},
|
||||
}));
|
||||
@@ -1,5 +1,4 @@
|
||||
import fs from "node:fs/promises";
|
||||
import asTableModule from "as-table";
|
||||
import events from "events";
|
||||
import os from "os";
|
||||
import child_process from "child_process";
|
||||
@@ -7,10 +6,10 @@ import child_process from "child_process";
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
import { asTable, print } from "./command_ops.js";
|
||||
import {
|
||||
serializedConfigToString, getEditor, configToKeyVal, printConfig, printRestartRequired,
|
||||
} from "./config_ops.js";
|
||||
|
||||
export const hostCommands = new lib.CommandTree({ name: "host", description: "Host management" });
|
||||
hostCommands.add(new lib.Command({
|
||||
@@ -46,67 +45,87 @@ hostCommands.add(new lib.Command({
|
||||
hostCommands.add(new lib.Command({
|
||||
definition: [["list", "l"], "List hosts connected to the controller"],
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
let hosts = await ctl.send(new lib.HostListRequest());
|
||||
print(asTable(hosts));
|
||||
ctl.output.table(await ctl.send(new lib.HostListRequest()));
|
||||
},
|
||||
}));
|
||||
|
||||
/** Format a duration in milliseconds as a short age like "1m 5s" */
|
||||
function formatAge(ms: number) {
|
||||
const seconds = Math.max(0, Math.floor(ms / 1000));
|
||||
if (seconds < 60) {
|
||||
return `${seconds}s`;
|
||||
}
|
||||
if (seconds < 3600) {
|
||||
return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
|
||||
}
|
||||
return `${Math.floor(seconds / 3600)}h ${Math.floor(seconds / 60) % 60}m`;
|
||||
}
|
||||
|
||||
/** Strip case and separators the same way the controller does when matching pairing codes */
|
||||
function plainCode(code: string) {
|
||||
return code.toUpperCase().replace(/[^0-9A-Z]/g, "");
|
||||
}
|
||||
|
||||
hostCommands.add(new lib.Command({
|
||||
definition: ["pending", "List host installers waiting for approval"],
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
let requests = await ctl.send(new lib.HostPairingListRequest());
|
||||
ctl.output.result(requests, () => {
|
||||
if (!requests.length) {
|
||||
print("No pending host requests");
|
||||
return;
|
||||
}
|
||||
let now = Date.now();
|
||||
print(asTable(requests.map(request => ({
|
||||
code: request.code,
|
||||
name: request.name,
|
||||
address: request.remoteAddress,
|
||||
age: formatAge(now - request.createdAtMs),
|
||||
}))));
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
hostCommands.add(new lib.Command({
|
||||
definition: ["generate-token", "Generate token for a host", (yargs) => {
|
||||
yargs.option("id", { type: "number", nargs: 1, describe: "Host id" });
|
||||
definition: ["approve <code>", "Approve a host installer waiting for approval", (yargs) => {
|
||||
yargs.positional("code", { describe: "Code shown by the installer", type: "string" });
|
||||
yargs.option("name", {
|
||||
type: "string", nargs: 1, describe: "Name to give the host instead of the one it asked for",
|
||||
});
|
||||
}],
|
||||
handler: async function(args: { id?: number }, ctl: Ctl) {
|
||||
let hostId = typeof args.id === "number" ? args.id : undefined;
|
||||
let response = await ctl.send(new lib.HostGenerateTokenRequest(hostId));
|
||||
print(response);
|
||||
handler: async function(args: { code: string, name?: string }, ctl: Ctl) {
|
||||
let name = args.name?.trim();
|
||||
if (name === undefined) {
|
||||
let requests = await ctl.send(new lib.HostPairingListRequest());
|
||||
name = requests.find(request => plainCode(request.code) === plainCode(args.code))?.name;
|
||||
}
|
||||
let hostId = await ctl.send(new lib.HostPairingApproveRequest(args.code, args.name));
|
||||
ctl.output.result(
|
||||
{ id: hostId, name },
|
||||
() => print(name ? `Approved host ${name} with id ${hostId}` : `Approved host with id ${hostId}`),
|
||||
);
|
||||
},
|
||||
}));
|
||||
|
||||
hostCommands.add(new lib.Command({
|
||||
definition: ["revoke-token <host>", "Revoke all tokens for a host", (yargs) => {
|
||||
yargs.positional("host", { describe: "Host to revoke tokens for", type: "string" });
|
||||
definition: ["reject <code>", "Reject a host installer waiting for approval", (yargs) => {
|
||||
yargs.positional("code", { describe: "Code shown by the installer", type: "string" });
|
||||
}],
|
||||
handler: async function(args: { code: string }, ctl: Ctl) {
|
||||
await ctl.send(new lib.HostPairingRejectRequest(args.code));
|
||||
},
|
||||
}));
|
||||
|
||||
hostCommands.add(new lib.Command({
|
||||
definition: ["revoke <host>", "Remove a host from the cluster and disconnect it", (yargs) => {
|
||||
yargs.positional("host", { describe: "Host to revoke", type: "string" });
|
||||
}],
|
||||
handler: async function(args: { host: string }, ctl: Ctl) {
|
||||
let hostId = await lib.resolveHost(ctl, args.host);
|
||||
await ctl.send(new lib.HostRevokeTokensRequest(hostId));
|
||||
await ctl.send(new lib.HostRevokeRequest(hostId));
|
||||
},
|
||||
}));
|
||||
|
||||
hostCommands.add(new lib.Command({
|
||||
definition: ["create-config", "Create host config", (yargs) => {
|
||||
yargs.option("id", { type: "number", nargs: 1, describe: "Host id" });
|
||||
yargs.option("name", { type: "string", nargs: 1, describe: "Host name" });
|
||||
yargs.option("generate-token", {
|
||||
type: "boolean", nargs: 0, describe: "Generate authentication token", default: false,
|
||||
});
|
||||
yargs.option("output", {
|
||||
type: "string", nargs: 1, describe: "Path to output config (- for stdout)", default: "config-host.json",
|
||||
});
|
||||
}],
|
||||
handler: async function(
|
||||
args: { id?: number, name?: string, generateToken: boolean, output: string },
|
||||
ctl: Ctl
|
||||
) {
|
||||
let config = await ctl.send(
|
||||
new lib.HostConfigCreateRequest(args.id, args.name, args.generateToken)
|
||||
);
|
||||
|
||||
let content = JSON.stringify(config, null, "\t");
|
||||
if (args.output === "-") {
|
||||
print(content);
|
||||
} else {
|
||||
logger.info(`Writing ${args.output}`);
|
||||
try {
|
||||
await fs.writeFile(args.output, content, { flag: "wx", mode: 0o600 });
|
||||
} catch (err: any) {
|
||||
if (err.code === "EEXIST") {
|
||||
throw new lib.CommandError(`File ${args.output} already exists`);
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
},
|
||||
}));
|
||||
hostCommands.add(new lib.Command({
|
||||
definition: ["update <host>", "Update the host", (yargs) => {
|
||||
yargs.positional("host", { describe: "Host to update", type: "string" });
|
||||
@@ -122,9 +141,8 @@ hostCommands.add(new lib.Command({
|
||||
}
|
||||
if (args.restart) {
|
||||
await ctl.sendTo({ hostId }, new lib.HostRestartRequest());
|
||||
} else {
|
||||
print("Host updated; a restart is required to apply the changes.");
|
||||
}
|
||||
printRestartRequired(ctl, !args.restart, "Host updated");
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -138,11 +156,7 @@ hostConfigCommands.add(new lib.Command({
|
||||
}],
|
||||
handler: async function(args: { host: string }, ctl: Ctl) {
|
||||
let hostId = await lib.resolveHost(ctl, args.host);
|
||||
let config = await ctl.sendTo({ hostId }, new lib.HostConfigGetRequest());
|
||||
|
||||
for (let [name, value] of Object.entries(config)) {
|
||||
print(`${name} ${JSON.stringify(value)}`);
|
||||
}
|
||||
printConfig(ctl, await ctl.sendTo({ hostId }, new lib.HostConfigGetRequest()));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -240,19 +254,22 @@ hostConfigCommands.add(new lib.Command({
|
||||
index,
|
||||
final[index],
|
||||
));
|
||||
} catch (err) {
|
||||
// eslint-disable-next-line
|
||||
print(`Attempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`);
|
||||
} catch (err: any) {
|
||||
// If the string is empty, it's better to just print "" instead of nothing
|
||||
print(err);
|
||||
logger.error(
|
||||
`Attempt to set ${index} to ${final[index] || String(null)} failed; ` +
|
||||
`set back to previous value: ${err.message}`
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
try {
|
||||
await fs.unlink(tmpFile);
|
||||
} catch (err) {
|
||||
print("err: temporary file", tmpFile, "could not be deleted.");
|
||||
print("This is not fatal, but they may build up over time if the issue persists.");
|
||||
logger.warn(
|
||||
`Temporary file ${tmpFile} could not be deleted. ` +
|
||||
"This is not fatal, but they may build up over time if the issue persists."
|
||||
);
|
||||
}
|
||||
},
|
||||
}));
|
||||
@@ -270,9 +287,9 @@ hostPluginCommands.add(new lib.Command({
|
||||
handler: async function(args: { host: string }, ctl: Ctl) {
|
||||
let hostId = await lib.resolveHost(ctl, args.host);
|
||||
const plugins = await ctl.sendTo({ hostId }, new lib.PluginListRequest());
|
||||
print(asTable(plugins.map(p => ({
|
||||
title: p.title, version: p.version, loaded: p.loaded, enabled: p.enabled, npmPackage: p.npmPackage,
|
||||
}))));
|
||||
ctl.output.table(plugins, p => ({
|
||||
title: p.title, version: p.version, state: p.state, npmPackage: p.npmPackage,
|
||||
}));
|
||||
},
|
||||
}));
|
||||
hostPluginCommands.add(new lib.Command({
|
||||
@@ -286,9 +303,8 @@ hostPluginCommands.add(new lib.Command({
|
||||
await ctl.sendTo({ hostId }, new lib.PluginUpdateRequest(args.plugin));
|
||||
if (args.restart) {
|
||||
await ctl.sendTo({ hostId }, new lib.HostRestartRequest());
|
||||
} else {
|
||||
print("Plugin updated; a restart is required to apply the changes.");
|
||||
}
|
||||
printRestartRequired(ctl, !args.restart, "Plugin updated");
|
||||
},
|
||||
}));
|
||||
hostPluginCommands.add(new lib.Command({
|
||||
@@ -302,9 +318,8 @@ hostPluginCommands.add(new lib.Command({
|
||||
await ctl.sendTo({ hostId }, new lib.PluginInstallRequest(args.plugin));
|
||||
if (args.restart) {
|
||||
await ctl.sendTo({ hostId }, new lib.HostRestartRequest());
|
||||
} else {
|
||||
print("Plugin installed; a restart is required to apply the changes.");
|
||||
}
|
||||
printRestartRequired(ctl, !args.restart, "Plugin installed");
|
||||
},
|
||||
}));
|
||||
hostCommands.add(hostPluginCommands);
|
||||
@@ -1,5 +1,4 @@
|
||||
import fs from "node:fs/promises";
|
||||
import asTableModule from "as-table";
|
||||
import events from "events";
|
||||
import path from "path";
|
||||
import os from "os";
|
||||
@@ -10,20 +9,23 @@ import util from "util";
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops.js";
|
||||
import { errorToJson, print } from "./command_ops.js";
|
||||
import { serializedConfigToString, getEditor, configToKeyVal, printConfig } from "./config_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
const finished = util.promisify(stream.finished);
|
||||
|
||||
export const instanceCommands = new lib.CommandTree({
|
||||
name: "instance", alias: ["i"], description: "Instance management",
|
||||
});
|
||||
instanceCommands.add(new lib.Command({
|
||||
definition: [["list", "l"], "List instances known to the controller"],
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
definition: [["list", "l"], "List instances known to the controller", (yargs) => {
|
||||
yargs.options({
|
||||
"templates": { describe: "Include templates", nargs: 0, type: "boolean", default: false },
|
||||
});
|
||||
}],
|
||||
handler: async function(args: { templates: boolean }, ctl: Ctl) {
|
||||
let list = await ctl.send(new lib.InstanceDetailsListRequest());
|
||||
print(asTable(list));
|
||||
ctl.output.table(list.filter(instance => args.templates || !instance.isTemplate));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -34,20 +36,33 @@ instanceCommands.add(new lib.Command({
|
||||
yargs.options({
|
||||
"id": { type: "number", nargs: 1, describe: "Instance id" },
|
||||
"from": { type: "number", nargs: 1, describe: "Clone config from instance id" },
|
||||
"template": { type: "string", nargs: 1, describe: "Template to inherit config from" },
|
||||
"as-template": { type: "boolean", nargs: 0, describe: "Create the instance as a template" },
|
||||
});
|
||||
}],
|
||||
handler: async function(args: { name: string, id?: number, from?: number, }, ctl: Ctl) {
|
||||
handler: async function(
|
||||
args: { name: string, id?: number, from?: number, template?: string, asTemplate?: boolean },
|
||||
ctl: Ctl,
|
||||
) {
|
||||
let instanceConfig = new lib.InstanceConfig("control");
|
||||
let fields: (keyof lib.InstanceConfigFields)[] = ["instance.id", "instance.name"];
|
||||
if (args.id !== undefined) {
|
||||
instanceConfig.set("instance.id", args.id);
|
||||
}
|
||||
instanceConfig.set("instance.name", args.name);
|
||||
if (args.template !== undefined) {
|
||||
instanceConfig.set("instance.template_id", await lib.resolveInstance(ctl, args.template));
|
||||
fields.push("instance.template_id");
|
||||
}
|
||||
if (args.asTemplate) {
|
||||
instanceConfig.set("instance.is_template", true);
|
||||
fields.push("instance.is_template");
|
||||
}
|
||||
await ctl.send(new lib.InstanceCreateRequest(
|
||||
instanceConfig.toRemote("controller", [
|
||||
"instance.id", "instance.name",
|
||||
]),
|
||||
instanceConfig.toRemote("controller", fields),
|
||||
args.from
|
||||
));
|
||||
ctl.output.result({ id: instanceConfig.get("instance.id") }, () => {});
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -61,10 +76,33 @@ instanceConfigCommands.add(new lib.Command({
|
||||
handler: async function(args: { instance: string }, ctl: Ctl) {
|
||||
let instanceId = await lib.resolveInstance(ctl, args.instance);
|
||||
let config = await ctl.send(new lib.InstanceConfigGetRequest(instanceId));
|
||||
const inherited = config["instance.template_id"] !== null
|
||||
? config["instance.inherited_fields"] as Record<string, true | string[]> ?? {}
|
||||
: {};
|
||||
|
||||
for (let [name, value] of Object.entries(config)) {
|
||||
print(`${name} ${JSON.stringify(value)}`);
|
||||
}
|
||||
printConfig(ctl, config, name => {
|
||||
const entry = inherited[name];
|
||||
if (entry instanceof Array && entry.length) {
|
||||
return ` (inherited except ${entry.join(", ")})`;
|
||||
}
|
||||
return entry ? " (inherited)" : "";
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
instanceConfigCommands.add(new lib.Command({
|
||||
definition: [
|
||||
"inherit <instance> <field> [prop]",
|
||||
"Make field or property in instance config use the value of its template",
|
||||
(yargs) => {
|
||||
yargs.positional("instance", { describe: "Instance to update config on", type: "string" });
|
||||
yargs.positional("field", { describe: "Field to inherit", type: "string" });
|
||||
yargs.positional("prop", { describe: "Property of object field to inherit", type: "string" });
|
||||
},
|
||||
],
|
||||
handler: async function(args: { instance: string, field: string, prop?: string }, ctl: Ctl) {
|
||||
let instanceId = await lib.resolveInstance(ctl, args.instance);
|
||||
await ctl.send(new lib.InstanceConfigInheritFieldRequest(instanceId, args.field, args.prop));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -170,27 +208,32 @@ instanceConfigCommands.add(new lib.Command({
|
||||
await events.once(editorSpawn, "exit");
|
||||
const data = await fs.readFile(tmpFile, "utf8");
|
||||
const final = await configToKeyVal(data);
|
||||
const original = await configToKeyVal(allConfigElements);
|
||||
for (let index in final) {
|
||||
if (index in final) {
|
||||
// Unchanged fields are skipped so they keep inheriting from the template
|
||||
if (index in final && final[index] !== original[index]) {
|
||||
try {
|
||||
await ctl.send(new lib.InstanceConfigSetFieldRequest(
|
||||
instanceId,
|
||||
index,
|
||||
final[index],
|
||||
));
|
||||
} catch (err) {
|
||||
// eslint-disable-next-line
|
||||
print(`Attempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`);
|
||||
} catch (err: any) {
|
||||
// If the string is empty, it's better to just print "" instead of nothing
|
||||
print(err);
|
||||
logger.error(
|
||||
`Attempt to set ${index} to ${final[index] || String(null)} failed; ` +
|
||||
`set back to previous value: ${err.message}`
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
try {
|
||||
await fs.unlink(tmpFile);
|
||||
} catch (err) {
|
||||
print("err: temporary file", tmpFile, "could not be deleted.");
|
||||
print("This is not fatal, but they may build up over time if the issue persists.");
|
||||
logger.warn(
|
||||
`Temporary file ${tmpFile} could not be deleted. ` +
|
||||
"This is not fatal, but they may build up over time if the issue persists."
|
||||
);
|
||||
}
|
||||
},
|
||||
}));
|
||||
@@ -244,9 +287,7 @@ instanceSaveCommands.add(new lib.Command({
|
||||
let instanceId = await lib.resolveInstance(ctl, args.instance);
|
||||
let saves = await ctl.sendTo("controller", new lib.InstanceSaveDetailsListRequest());
|
||||
saves = saves.filter(save => save.instanceId === instanceId);
|
||||
print(asTable(saves.map(
|
||||
({ mtimeMs, ...rest }) => ({ ...rest, mtime: new Date(mtimeMs).toLocaleString() })
|
||||
)));
|
||||
ctl.output.table(saves, ({ mtimeMs, ...rest }) => ({ ...rest, mtime: new Date(mtimeMs).toLocaleString() }));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -347,13 +388,16 @@ instanceSaveCommands.add(new lib.Command({
|
||||
logger.error(requestError);
|
||||
}
|
||||
|
||||
if (result.saves && result.saves.length) {
|
||||
logger.info(`Successfully uploaded as ${result.saves[0]}`);
|
||||
}
|
||||
|
||||
if ((result.errors || []).length || (result.request_errors || []).length) {
|
||||
throw new lib.CommandError("Uploading save failed");
|
||||
}
|
||||
|
||||
const name = result.saves?.[0];
|
||||
ctl.output.result({ name }, () => {
|
||||
if (name) {
|
||||
print(`Successfully uploaded as ${name}`);
|
||||
}
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -392,7 +436,10 @@ instanceSaveCommands.add(new lib.Command({
|
||||
args.copy
|
||||
)
|
||||
);
|
||||
print(`Transferred as ${storedName} to ${args.targetInstance}.`);
|
||||
ctl.output.result(
|
||||
{ name: storedName, instanceId: targetInstanceId },
|
||||
() => print(`Transferred as ${storedName} to ${args.targetInstance}.`),
|
||||
);
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -409,7 +456,10 @@ instanceSaveCommands.add(new lib.Command({
|
||||
url.pathname += `api/stream/${streamId}`;
|
||||
const filename = await lib.downloadFile(url, args.save, "rename");
|
||||
|
||||
logger.info(`Downloaded ${args.save}${args.save === filename ? "" : ` as ${filename}`}`);
|
||||
ctl.output.result(
|
||||
{ filename },
|
||||
() => print(`Downloaded ${args.save}${args.save === filename ? "" : ` as ${filename}`}`),
|
||||
);
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -519,27 +569,34 @@ instanceCommands.add(new lib.Command({
|
||||
});
|
||||
|
||||
if (instancesToStart.length === 0) {
|
||||
print("No instances to start.");
|
||||
ctl.output.result([], () => print("No instances to start."));
|
||||
return;
|
||||
}
|
||||
|
||||
print(`Starting ${instancesToStart.length} instance(s):`);
|
||||
for (const instance of instancesToStart) {
|
||||
print(` - ${instance.name} (ID: ${instance.id})`);
|
||||
const human = ctl.output.human;
|
||||
if (human) {
|
||||
print(`Starting ${instancesToStart.length} instance(s):`);
|
||||
for (const instance of instancesToStart) {
|
||||
print(` - ${instance.name} (ID: ${instance.id})`);
|
||||
}
|
||||
}
|
||||
|
||||
// Start all filtered instances
|
||||
const startPromises = instancesToStart.map(async (instance: lib.InstanceDetails) => {
|
||||
const results = await Promise.all(instancesToStart.map(async (instance: lib.InstanceDetails) => {
|
||||
try {
|
||||
await ctl.sendTo({ instanceId: instance.id }, new lib.InstanceStartRequest());
|
||||
print(`✓ Started ${instance.name}`);
|
||||
if (human) {
|
||||
print(`✓ Started ${instance.name}`);
|
||||
}
|
||||
return { id: instance.id, name: instance.name };
|
||||
} catch (error) {
|
||||
print(`✗ Failed to start ${instance.name}: ${error}`);
|
||||
if (human) {
|
||||
print(`✗ Failed to start ${instance.name}: ${error}`);
|
||||
}
|
||||
return { id: instance.id, name: instance.name, error: errorToJson(error) };
|
||||
}
|
||||
});
|
||||
|
||||
await Promise.all(startPromises);
|
||||
print("Start all operation completed.");
|
||||
}));
|
||||
ctl.output.result(results, () => print("Start all operation completed."));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -599,27 +656,34 @@ instanceCommands.add(new lib.Command({
|
||||
.filter((instance: lib.InstanceDetails) => ["starting", "running"].includes(instance.status));
|
||||
|
||||
if (instancesToStop.length === 0) {
|
||||
print("No instances to stop.");
|
||||
ctl.output.result([], () => print("No instances to stop."));
|
||||
return;
|
||||
}
|
||||
|
||||
print(`Stopping ${instancesToStop.length} instance(s):`);
|
||||
for (const instance of instancesToStop) {
|
||||
print(` - ${instance.name} (ID: ${instance.id})`);
|
||||
const human = ctl.output.human;
|
||||
if (human) {
|
||||
print(`Stopping ${instancesToStop.length} instance(s):`);
|
||||
for (const instance of instancesToStop) {
|
||||
print(` - ${instance.name} (ID: ${instance.id})`);
|
||||
}
|
||||
}
|
||||
|
||||
// Stop all filtered instances
|
||||
const stopPromises = instancesToStop.map(async (instance: lib.InstanceDetails) => {
|
||||
const results = await Promise.all(instancesToStop.map(async (instance: lib.InstanceDetails) => {
|
||||
try {
|
||||
await ctl.sendTo({ instanceId: instance.id }, new lib.InstanceStopRequest());
|
||||
print(`✓ Stopped ${instance.name}`);
|
||||
if (human) {
|
||||
print(`✓ Stopped ${instance.name}`);
|
||||
}
|
||||
return { id: instance.id, name: instance.name };
|
||||
} catch (error) {
|
||||
print(`✗ Failed to stop ${instance.name}: ${error}`);
|
||||
if (human) {
|
||||
print(`✗ Failed to stop ${instance.name}: ${error}`);
|
||||
}
|
||||
return { id: instance.id, name: instance.name, error: errorToJson(error) };
|
||||
}
|
||||
});
|
||||
|
||||
await Promise.all(stopPromises);
|
||||
print("Stop all operation completed.");
|
||||
}));
|
||||
ctl.output.result(results, () => print("Stop all operation completed."));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -656,6 +720,6 @@ instanceCommands.add(new lib.Command({
|
||||
);
|
||||
|
||||
// Factorio includes a newline in its response output.
|
||||
process.stdout.write(result);
|
||||
ctl.output.result({ result }, () => process.stdout.write(result));
|
||||
},
|
||||
}));
|
||||
@@ -27,6 +27,7 @@ logCommands.add(new lib.Command({
|
||||
let hostIds = args.host ? [await lib.resolveHost(ctl, args.host)] : [];
|
||||
await ctl.setLogSubscriptions({ all: args.all, controller: args.controller, hostIds, instanceIds });
|
||||
ctl.keepOpen = true;
|
||||
ctl.output.streamingLog = true;
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -75,16 +76,18 @@ logCommands.add(new lib.Command({
|
||||
result.log.reverse();
|
||||
}
|
||||
|
||||
let stdoutLogger = winston.createLogger({
|
||||
level: "verbose",
|
||||
levels,
|
||||
format: new lib.TerminalFormat({ showTimestamp: true }),
|
||||
transports: [
|
||||
new ConsoleTransport({ errorLevels: [], warnLevels: [] }),
|
||||
],
|
||||
ctl.output.result(result.log, () => {
|
||||
let stdoutLogger = winston.createLogger({
|
||||
level: "verbose",
|
||||
levels,
|
||||
format: new lib.TerminalFormat({ showTimestamp: true }),
|
||||
transports: [
|
||||
new ConsoleTransport({ errorLevels: [], warnLevels: [] }),
|
||||
],
|
||||
});
|
||||
for (let info of result.log) {
|
||||
stdoutLogger.log(info as any);
|
||||
}
|
||||
});
|
||||
for (let info of result.log) {
|
||||
stdoutLogger.log(info as any);
|
||||
}
|
||||
},
|
||||
}));
|
||||
@@ -1,5 +1,4 @@
|
||||
import fs from "node:fs/promises";
|
||||
import asTableModule from "as-table";
|
||||
import events from "events";
|
||||
import path from "path";
|
||||
import stream from "stream";
|
||||
@@ -8,9 +7,7 @@ import util from "util";
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
import { asTable, pickFields, print } from "./command_ops.js";
|
||||
const finished = util.promisify(stream.finished);
|
||||
|
||||
export const modCommands = new lib.CommandTree({ name: "mod", description: "Manage uploaded mods" });
|
||||
@@ -24,16 +21,18 @@ modCommands.add(new lib.Command({
|
||||
throw new lib.CommandError("mod-version must match format digit.digit.digit");
|
||||
}
|
||||
let modInfo = await ctl.send(new lib.ModGetRequest(args.name, args.modVersion));
|
||||
for (let [field, value] of Object.entries(modInfo)) {
|
||||
if (value instanceof Array) {
|
||||
print(`${field}:`);
|
||||
for (let entry of value) {
|
||||
print(` ${entry}`);
|
||||
ctl.output.result(modInfo, () => {
|
||||
for (let [field, value] of Object.entries(modInfo)) {
|
||||
if (value instanceof Array) {
|
||||
print(`${field}:`);
|
||||
for (let entry of value) {
|
||||
print(` ${entry}`);
|
||||
}
|
||||
} else {
|
||||
print(`${field}: ${value}`);
|
||||
}
|
||||
} else {
|
||||
print(`${field}: ${value}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -50,17 +49,7 @@ modCommands.add(new lib.Command({
|
||||
}],
|
||||
handler: async function(args: { fields: string[] }, ctl: Ctl) {
|
||||
let mods = await ctl.send(new lib.ModListRequest());
|
||||
if (!args.fields.includes("all")) {
|
||||
for (let entry of mods) {
|
||||
for (let field of Object.keys(entry)) {
|
||||
if (!args.fields.includes(field)) {
|
||||
// @ts-expect-error terrible hack
|
||||
delete entry[field];
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
print(asTable(mods));
|
||||
ctl.output.table(mods, mod => pickFields(mod, args.fields));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -121,21 +110,19 @@ modCommands.add(new lib.Command({
|
||||
args.sortOrder
|
||||
));
|
||||
let results = response.results.flatMap(result => result.versions);
|
||||
if (!args.fields.includes("all")) {
|
||||
for (let entry of results) {
|
||||
for (let field of Object.keys(entry)) {
|
||||
if (!args.fields.includes(field)) {
|
||||
// @ts-expect-error terrible hack
|
||||
delete entry[field];
|
||||
}
|
||||
}
|
||||
ctl.output.result({
|
||||
page: args.page,
|
||||
pageCount: response.pageCount,
|
||||
resultCount: response.resultCount,
|
||||
queryIssues: response.queryIssues,
|
||||
results,
|
||||
}, () => {
|
||||
for (let issue of response.queryIssues) {
|
||||
print(issue);
|
||||
}
|
||||
}
|
||||
for (let issue of response.queryIssues) {
|
||||
print(issue);
|
||||
}
|
||||
print(`page ${args.page} of ${response.pageCount} (${response.resultCount} results)`);
|
||||
print(asTable(results));
|
||||
print(`page ${args.page} of ${response.pageCount} (${response.resultCount} results)`);
|
||||
print(asTable(results.map(mod => pickFields(mod, args.fields))));
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -174,14 +161,16 @@ modCommands.add(new lib.Command({
|
||||
logger.error(requestError);
|
||||
}
|
||||
|
||||
if (result.mods && result.mods.length) {
|
||||
const mod = lib.ModInfo.fromJSON(result.mods[0]);
|
||||
logger.info(`Successfully uploaded ${mod.filename}`);
|
||||
}
|
||||
|
||||
if ((result.errors || []).length || (result.request_errors || []).length) {
|
||||
throw new lib.CommandError("Uploading mod failed");
|
||||
}
|
||||
|
||||
const uploaded = result.mods?.length ? lib.ModInfo.fromJSON(result.mods[0]).filename : undefined;
|
||||
ctl.output.result({ filename: uploaded }, () => {
|
||||
if (uploaded) {
|
||||
print(`Successfully uploaded ${uploaded}`);
|
||||
}
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -201,7 +190,7 @@ modCommands.add(new lib.Command({
|
||||
let filename = `${args.name}_${args.modVersion}.zip`;
|
||||
await lib.downloadFile(url, filename, "overwrite");
|
||||
|
||||
logger.info(`Downloaded ${filename}`);
|
||||
ctl.output.result({ filename }, () => print(`Downloaded ${filename}`));
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -1,11 +1,7 @@
|
||||
import asTableModule from "as-table";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
import { pickFields, print } from "./command_ops.js";
|
||||
|
||||
export const modPackCommands = new lib.CommandTree({ name: "mod-pack", description: "Mod Pack" });
|
||||
modPackCommands.add(new lib.Command({
|
||||
@@ -19,56 +15,50 @@ modPackCommands.add(new lib.Command({
|
||||
let modPack = await ctl.send(
|
||||
new lib.ModPackGetRequest(await lib.resolveModPack(ctl, args.modPack))
|
||||
);
|
||||
|
||||
for (let [field, value] of Object.entries(modPack)) {
|
||||
if (field === "mods") {
|
||||
print(`${field}:`);
|
||||
for (let [name, entry] of value) {
|
||||
const mod = mods.get(`${name}_${entry.version}`);
|
||||
const missing = !mod && "? ";
|
||||
const badChecksum = mod && entry.sha1 && entry.sha1 !== mod.sha1 && "! ";
|
||||
const warn = missing || badChecksum || "";
|
||||
const enabled = entry.enabled ? "" : "(disabled) ";
|
||||
print(` ${warn}${enabled}${name} ${entry.version}${entry.sha1 ? ` (${entry.sha1})` : ""}`);
|
||||
}
|
||||
} else if (field === "settings") {
|
||||
print(`${field}:`);
|
||||
for (let [scope, settings] of Object.entries(value)) {
|
||||
print(` ${scope}:`);
|
||||
for (let [setting, settingValue] of settings as any) {
|
||||
print(` ${setting}: ${JSON.stringify(settingValue.value)}`);
|
||||
}
|
||||
}
|
||||
} else if (field === "exportManifest") {
|
||||
print(`${field}:`);
|
||||
if (value && value.assets) {
|
||||
print(" assets:");
|
||||
for (let [name, fileName] of Object.entries(value.assets)) {
|
||||
print(` ${name}: ${fileName}`);
|
||||
}
|
||||
}
|
||||
|
||||
} else {
|
||||
print(`${field}: ${value}`);
|
||||
}
|
||||
}
|
||||
ctl.output.result(modPack, () => printModPack(modPack, mods));
|
||||
},
|
||||
}));
|
||||
|
||||
function printModPack(modPack: lib.ModPack, mods: Map<string, lib.ModInfo>) {
|
||||
for (let [field, value] of Object.entries(modPack)) {
|
||||
if (field === "mods") {
|
||||
print(`${field}:`);
|
||||
for (let [name, entry] of value) {
|
||||
const mod = mods.get(`${name}_${entry.version}`);
|
||||
const missing = !mod && "? ";
|
||||
const badChecksum = mod && entry.sha1 && entry.sha1 !== mod.sha1 && "! ";
|
||||
const warn = missing || badChecksum || "";
|
||||
const enabled = entry.enabled ? "" : "(disabled) ";
|
||||
print(` ${warn}${enabled}${name} ${entry.version}${entry.sha1 ? ` (${entry.sha1})` : ""}`);
|
||||
}
|
||||
} else if (field === "settings") {
|
||||
print(`${field}:`);
|
||||
for (let [scope, settings] of Object.entries(value)) {
|
||||
print(` ${scope}:`);
|
||||
for (let [setting, settingValue] of settings as any) {
|
||||
print(` ${setting}: ${JSON.stringify(settingValue.value)}`);
|
||||
}
|
||||
}
|
||||
} else if (field === "exportManifest") {
|
||||
print(`${field}:`);
|
||||
if (value && value.assets) {
|
||||
print(" assets:");
|
||||
for (let [name, fileName] of Object.entries(value.assets)) {
|
||||
print(` ${name}: ${fileName}`);
|
||||
}
|
||||
}
|
||||
|
||||
} else {
|
||||
print(`${field}: ${value}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
modPackCommands.add(new lib.Command({
|
||||
definition: [["list", "l"], "List mod packs in the cluster"],
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
let modPacks = await ctl.send(new lib.ModPackListRequest());
|
||||
let fields = ["id", "name", "factorioVersion"];
|
||||
for (let entry of modPacks) {
|
||||
for (let field of Object.keys(entry)) {
|
||||
if (!fields.includes(field)) {
|
||||
// @ts-expect-error terrible hack
|
||||
delete entry[field];
|
||||
}
|
||||
}
|
||||
}
|
||||
print(asTable(modPacks));
|
||||
ctl.output.table(modPacks, modPack => pickFields(modPack, ["id", "name", "factorioVersion"]));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -194,10 +184,17 @@ modPackCommands.add(new lib.Command({
|
||||
setModPackModsEnabled(modPack, args.disabledMods, false);
|
||||
setModPackSettings(modPack, args);
|
||||
await ctl.send(new lib.ModPackCreateRequest(modPack));
|
||||
print(`Created mod pack ${modPack.name} (${modPack.id})`);
|
||||
printCreated(ctl, modPack);
|
||||
},
|
||||
}));
|
||||
|
||||
function printCreated(ctl: Ctl, modPack: lib.ModPack) {
|
||||
ctl.output.result(
|
||||
{ id: modPack.id, name: modPack.name },
|
||||
() => print(`Created mod pack ${modPack.name} (${modPack.id})`),
|
||||
);
|
||||
}
|
||||
|
||||
modPackCommands.add(new lib.Command({
|
||||
definition: ["import <string>", "Import mod pack string", (yargs) => {
|
||||
yargs.positional("string", { describe: "Mod pack string to import", type: "string" });
|
||||
@@ -205,7 +202,7 @@ modPackCommands.add(new lib.Command({
|
||||
handler: async function(args: { string: string }, ctl: Ctl) {
|
||||
const modPack = lib.ModPack.fromModPackString(args.string);
|
||||
await ctl.send(new lib.ModPackCreateRequest(modPack));
|
||||
print(`Created mod pack ${modPack.name} (${modPack.id})`);
|
||||
printCreated(ctl, modPack);
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -217,7 +214,8 @@ modPackCommands.add(new lib.Command({
|
||||
const modPack = await ctl.send(
|
||||
new lib.ModPackGetRequest(await lib.resolveModPack(ctl, args.modPack))
|
||||
);
|
||||
print(modPack.toModPackString());
|
||||
const modPackString = modPack.toModPackString();
|
||||
ctl.output.result({ modPackString }, () => print(modPackString));
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -1,11 +1,7 @@
|
||||
import asTableModule from "as-table";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
|
||||
export const noteCommands = new lib.CommandTree({
|
||||
name: "note", description: "Notes attached to hosts, instances, users and other resources",
|
||||
});
|
||||
@@ -20,12 +16,12 @@ noteCommands.add(new lib.Command({
|
||||
if (args.type !== undefined) {
|
||||
notes = notes.filter(note => note.resourceType === args.type);
|
||||
}
|
||||
print(asTable(notes.map(note => ({
|
||||
ctl.output.table(notes, note => ({
|
||||
type: note.resourceType,
|
||||
id: note.resourceId,
|
||||
updatedBy: note.updatedBy,
|
||||
content: note.content,
|
||||
}))));
|
||||
}));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -42,7 +38,7 @@ noteCommands.add(new lib.Command({
|
||||
if (!note) {
|
||||
throw new lib.CommandError(`No note for ${args.type} ${args.id}`);
|
||||
}
|
||||
print(note.content);
|
||||
ctl.output.result(note, () => print(note.content));
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -1,16 +1,10 @@
|
||||
import asTableModule from "as-table";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
|
||||
export const permissionCommands = new lib.CommandTree({ name: "permission", description: "Permission inspection" });
|
||||
permissionCommands.add(new lib.Command({
|
||||
definition: [["list", "l"], "List permissions in the cluster"],
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
let permissions = await ctl.send(new lib.PermissionListRequest());
|
||||
print(asTable(permissions));
|
||||
ctl.output.table(await ctl.send(new lib.PermissionListRequest()));
|
||||
},
|
||||
}));
|
||||
@@ -1,18 +1,13 @@
|
||||
import asTableModule from "as-table";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
|
||||
export const roleCommands = new lib.CommandTree({ name: "role", description: "Role management" });
|
||||
roleCommands.add(new lib.Command({
|
||||
definition: [["list", "l"], "List roles in the cluster"],
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
let roles = await ctl.send(new lib.RoleListRequest());
|
||||
print(asTable(roles));
|
||||
ctl.output.table(await ctl.send(new lib.RoleListRequest()));
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -30,7 +25,7 @@ roleCommands.add(new lib.Command({
|
||||
args.description,
|
||||
args.permissions,
|
||||
));
|
||||
logger.info(`Created role ID ${id}`);
|
||||
ctl.output.result({ id }, () => print(`Created role ID ${id}`));
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
import fs from "node:fs/promises";
|
||||
import asTableModule from "as-table";
|
||||
import path from "path";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
import { asTable, print } from "./command_ops.js";
|
||||
|
||||
const asTable = asTableModule.configure({ delimiter: " | " });
|
||||
function printProperties(object: object) {
|
||||
print(asTable(Object.entries(object).map(([property, value]) => ({ property, value }))));
|
||||
}
|
||||
|
||||
export const userCommands = new lib.CommandTree({ name: "user", alias: ["u"], description: "User management" });
|
||||
userCommands.add(new lib.Command({
|
||||
@@ -17,30 +18,23 @@ userCommands.add(new lib.Command({
|
||||
});
|
||||
}],
|
||||
handler: async function(args: { name: string, instanceStats: boolean }, ctl: Ctl) {
|
||||
let user = await ctl.send(new lib.UserGetRequest(args.name));
|
||||
Object.assign(user, user.playerStats);
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.playerStats;
|
||||
let instanceStats = user.instanceStats;
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.instanceStats;
|
||||
print(asTable(Object.entries(user).map(([property, value]) => ({ property, value }))));
|
||||
|
||||
if (args.instanceStats) {
|
||||
let instances = await ctl.send(new lib.InstanceDetailsListRequest());
|
||||
function instanceName(id: number) {
|
||||
let instance = instances.find(i => i.id === id);
|
||||
if (instance) {
|
||||
return instance.name;
|
||||
}
|
||||
return "<deleted>";
|
||||
const user = await ctl.send(new lib.UserGetRequest(args.name));
|
||||
const { playerStats, instanceStats, ...properties } = user;
|
||||
const instances = args.instanceStats && ctl.output.human
|
||||
? await ctl.send(new lib.InstanceDetailsListRequest())
|
||||
: [];
|
||||
ctl.output.result(user, () => {
|
||||
printProperties({ ...properties, ...playerStats });
|
||||
if (!args.instanceStats) {
|
||||
return;
|
||||
}
|
||||
for (let [id, playerInstanceStats] of instanceStats || []) {
|
||||
for (let [id, playerInstanceStats] of instanceStats) {
|
||||
const name = instances.find(i => i.id === id)?.name ?? "<deleted>";
|
||||
print();
|
||||
print(`Instance ${instanceName(id)} (${id}):`);
|
||||
print(asTable(Object.entries(playerInstanceStats).map(([property, value]) => ({ property, value }))));
|
||||
print(`Instance ${name} (${id}):`);
|
||||
printProperties(playerInstanceStats);
|
||||
}
|
||||
}
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -52,29 +46,17 @@ userCommands.add(new lib.Command({
|
||||
});
|
||||
}],
|
||||
handler: async function(args: { stats: boolean, attributes: boolean }, ctl: Ctl) {
|
||||
let users = await ctl.send(new lib.UserListRequest());
|
||||
for (let user of users) {
|
||||
if (args.stats) {
|
||||
Object.assign(user, user.playerStats);
|
||||
}
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.playerStats;
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.isDeleted;
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.banReason;
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.instanceStats;
|
||||
if (!args.attributes) {
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.isAdmin;
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.isWhitelisted;
|
||||
// @ts-expect-error Terrible hack
|
||||
delete user.isBanned;
|
||||
}
|
||||
}
|
||||
print(asTable(users));
|
||||
const users = await ctl.send(new lib.UserListRequest());
|
||||
ctl.output.table(users, user => {
|
||||
const {
|
||||
playerStats, isDeleted, banReason, instanceStats, isAdmin, isWhitelisted, isBanned, ...row
|
||||
} = user;
|
||||
return {
|
||||
...row,
|
||||
...args.attributes && { isAdmin, isWhitelisted, isBanned },
|
||||
...args.stats && playerStats,
|
||||
};
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
@@ -222,11 +204,17 @@ async function handleImportOrRestore(args: {
|
||||
new lib.UserBulkImportRequest(importType, importType === "users" ? data.users : data, restore)
|
||||
);
|
||||
|
||||
print(`${restore ? "Restored" : "Imported"} ${importType} from ${args.filepath}`);
|
||||
let backupFile: string | undefined;
|
||||
if (restore && backup && !args.noBackup) {
|
||||
await fs.writeFile(`${importType}-backup.json`, JSON.stringify(backup, undefined, "\t"));
|
||||
print(`Wrote backup to ${importType}-backup.json`);
|
||||
backupFile = `${importType}-backup.json`;
|
||||
await fs.writeFile(backupFile, JSON.stringify(backup, undefined, "\t"));
|
||||
}
|
||||
ctl.output.result({ type: importType, backupFile }, () => {
|
||||
print(`${restore ? "Restored" : "Imported"} ${importType} from ${args.filepath}`);
|
||||
if (backupFile) {
|
||||
print(`Wrote backup to ${backupFile}`);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
userCommands.add(new lib.Command({
|
||||
@@ -299,6 +287,9 @@ userCommands.add(new lib.Command({
|
||||
await fs.writeFile(args.filepath, JSON.stringify(await ctl.send(
|
||||
new lib.UserBulkExportRequest(exportType)
|
||||
), undefined, "\t"));
|
||||
print(`Exported ${exportType} to ${args.filepath}`);
|
||||
ctl.output.result(
|
||||
{ type: exportType, filepath: args.filepath },
|
||||
() => print(`Exported ${exportType} to ${args.filepath}`),
|
||||
);
|
||||
},
|
||||
}));
|
||||
@@ -1,4 +1,6 @@
|
||||
import * as lib from "@clusterio/lib";
|
||||
import type { Ctl } from "../ctl.js";
|
||||
import { print } from "./command_ops.js";
|
||||
|
||||
export async function getEditor(argsEditor: string) {
|
||||
// eslint-disable-next-line
|
||||
@@ -53,3 +55,24 @@ export function serializedConfigToString(
|
||||
}
|
||||
return allConfigElements;
|
||||
}
|
||||
|
||||
/** Print config fields as `name value` lines, or as an object in json mode */
|
||||
export function printConfig(ctl: Ctl, config: lib.ConfigSchema, note = (name: string) => "") {
|
||||
ctl.output.result(config, () => {
|
||||
for (let [name, value] of Object.entries(config)) {
|
||||
// Shown as an (inherited) note on each field by instance config list instead
|
||||
if (name !== "instance.inherited_fields") {
|
||||
print(`${name} ${JSON.stringify(value)}${note(name)}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/** Print whether a restart is still needed after an update or install */
|
||||
export function printRestartRequired(ctl: Ctl, restartRequired: boolean, action: string) {
|
||||
ctl.output.result({ restartRequired }, () => {
|
||||
if (restartRequired) {
|
||||
print(`${action}; a restart is required to apply the changes.`);
|
||||
}
|
||||
});
|
||||
}
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"entryPoints": ["index.ts"],
|
||||
"includeVersion": true
|
||||
}
|
||||
@@ -132,6 +132,10 @@ Lists up all configuration entries with their currently configured values.
|
||||
### `run`
|
||||
|
||||
Runs the host.
|
||||
A host that has not been approved prints a code and a link and waits for approval before it connects, see [Setting up a host](https://github.com/clusterio/clusterio/blob/master/packages/create/README.md#setting-up-a-host).
|
||||
If the controller no longer accepts the token of the host when it starts, for example because the host was revoked, it asks to be approved again.
|
||||
If its request is rejected it exits with code 8 and the run scripts created by the installer do not restart it.
|
||||
A host that is revoked while it runs shuts down.
|
||||
|
||||
|
||||
## See Also
|
||||
|
||||
+48
-18
@@ -17,14 +17,16 @@ 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.
|
||||
import "./src/set_lazy_schema_compilation.js";
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { ConsoleTransport, levels, logger } from "@clusterio/lib";
|
||||
|
||||
import Host from "./src/Host.js";
|
||||
import type Host from "./src/Host.js";
|
||||
import { createScenarioCommand, handleCreateScenarioCommand } from "./src/create_scenario.js";
|
||||
import { PairingError, ensurePaired } from "./src/pairing.js";
|
||||
|
||||
let host: Host | undefined;
|
||||
|
||||
@@ -134,17 +136,20 @@ async function startHost() {
|
||||
type: "boolean", nargs: 0, default: false,
|
||||
describe: "Start the host in recovery mode with all plugins disabled and controller disconnected",
|
||||
});
|
||||
yargs.option("user-token", {
|
||||
type: "string", nargs: 1,
|
||||
describe: "Token of a user allowed to approve hosts, approves this host without waiting. Not saved",
|
||||
});
|
||||
})
|
||||
.demandCommand(1, "You need to specify a command to run")
|
||||
.strict()
|
||||
.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({
|
||||
@@ -203,6 +208,11 @@ async function startHost() {
|
||||
// From this point on the host should run
|
||||
await hostConfigLock.acquire();
|
||||
|
||||
lib.startLogRetention(
|
||||
[path.join(args.logDirectory, "host")],
|
||||
() => hostConfig.get("host.log_retention_days"),
|
||||
);
|
||||
|
||||
// If we get here the command was run
|
||||
await fs.mkdir(hostConfig.get("host.instances_directory"), { recursive: true });
|
||||
await fs.mkdir(hostConfig.get("host.mods_directory"), { recursive: true });
|
||||
@@ -212,19 +222,6 @@ async function startHost() {
|
||||
// and as the process name in ps/top on linux.
|
||||
process.title = "clusteriohost";
|
||||
|
||||
// make sure we have the controller access token
|
||||
if (hostConfig.get("host.controller_token") === "enter token here") {
|
||||
logger.fatal("ERROR invalid config!");
|
||||
logger.fatal(
|
||||
"Controller requires an access token for socket operations. As clusterio\n"+
|
||||
"hosts depends upon this, please set your token using the command npx\n"+
|
||||
"clusteriohost config set host.controller_token <token>. You can generate an\n"+
|
||||
"auth token using npx clusterioctl generate-host-token."
|
||||
);
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
// make sure url ends with /
|
||||
if (!hostConfig.get("host.controller_url").endsWith("/")) {
|
||||
logger.fatal("ERROR invalid config!");
|
||||
@@ -233,6 +230,39 @@ async function startHost() {
|
||||
return;
|
||||
}
|
||||
|
||||
if (!args.recovery) {
|
||||
const abort = new AbortController();
|
||||
const onSignal = () => { abort.abort(); };
|
||||
process.on("SIGINT", onSignal);
|
||||
process.on("SIGTERM", onSignal);
|
||||
process.on("SIGHUP", onSignal);
|
||||
try {
|
||||
await ensurePaired(hostConfig, {
|
||||
version: packageConfig.version,
|
||||
userToken: args.userToken as string | undefined,
|
||||
signal: abort.signal,
|
||||
});
|
||||
} catch (err: any) {
|
||||
if (abort.signal.aborted) {
|
||||
logger.info("Stopped waiting for approval");
|
||||
return;
|
||||
}
|
||||
if (err instanceof PairingError) {
|
||||
logger.fatal(`Unable to join the cluster: ${err.message}`);
|
||||
// Exit code 8 stops the run scripts from restarting the host.
|
||||
process.exitCode = err.status === 403 ? 8 : 1;
|
||||
return;
|
||||
}
|
||||
throw err;
|
||||
} finally {
|
||||
process.off("SIGINT", onSignal);
|
||||
process.off("SIGTERM", onSignal);
|
||||
process.off("SIGHUP", onSignal);
|
||||
}
|
||||
}
|
||||
|
||||
// Loaded here as the server is not needed by the other commands
|
||||
const { default: Host } = await import("./src/Host.js");
|
||||
let hostConnector = new HostConnector(hostConfig, pluginInfos);
|
||||
host = await Host.fromConfig(
|
||||
hostConfig,
|
||||
|
||||
@@ -4,6 +4,7 @@ export { BaseInstancePlugin, InstanceHooks, type InstancePluginContext } from ".
|
||||
export { default as Host, HostRouter } from "./src/Host.js";
|
||||
export { default as Instance } from "./src/Instance.js";
|
||||
export { default as InstanceConnection } from "./src/InstanceConnection.js";
|
||||
export { PairingError, checkHostToken, pairHost } from "./src/pairing.js";
|
||||
|
||||
if (import.meta.main) {
|
||||
bootstrap();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@clusterio/host",
|
||||
"version": "2.0.3",
|
||||
"version": "2.1.2",
|
||||
"description": "Implementation of Clusterio host server",
|
||||
"homepage": "https://github.com/clusterio/clusterio#readme",
|
||||
"author": "Hornwitser <github@hornwitser.no>",
|
||||
@@ -33,19 +33,22 @@
|
||||
"clusteriohost": "./dist/node/host.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
"node": "^22.18.0 || >=24.2.0"
|
||||
},
|
||||
|
||||
"dependencies": {
|
||||
"@clusterio/lib": "workspace:^",
|
||||
"@jimp/core": "^1.6.1",
|
||||
"@jimp/js-png": "^1.6.1",
|
||||
"@jimp/plugin-crop": "^1.6.1",
|
||||
"@jimp/plugin-resize": "^1.6.1",
|
||||
"@jimp/types": "^1.6.1",
|
||||
"@sinclair/typebox": "catalog:",
|
||||
"jimp": "^1.6.1",
|
||||
"pidusage": "^4.1.0",
|
||||
"rcon-client": "^4.2.5",
|
||||
"semver": "catalog:",
|
||||
"set-blocking": "catalog:",
|
||||
"winston": "catalog:",
|
||||
"winston-daily-rotate-file": "catalog:",
|
||||
"yargs": "catalog:",
|
||||
"yazl": "catalog:"
|
||||
},
|
||||
|
||||
+16
-19
@@ -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);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
+117
-29
@@ -11,7 +11,7 @@ const execAsync = util.promisify(exec);
|
||||
import * as lib from "@clusterio/lib";
|
||||
|
||||
import { FactorioServer, checkForUpdates } from "./server.js";
|
||||
import { loadModules, patch } from "./patch.js";
|
||||
import { loadModules, patch, unpatch } from "./patch.js";
|
||||
import { exportData } from "./export.js";
|
||||
import type Host from "./Host.js";
|
||||
import { BaseInstancePlugin, InstanceHooks } from "./BaseInstancePlugin.js";
|
||||
@@ -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) {
|
||||
@@ -693,7 +725,7 @@ end`.replace(/\r?\n/g, " ");
|
||||
players: [...this.playerStats],
|
||||
player_autosave_slot: this._playerAutosaveSlot,
|
||||
}, null, "\t");
|
||||
await lib.safeOutputFile(this.path("instance-stats.json"), content);
|
||||
await lib.atomicOverwriteFile(this.path("instance-stats.json"), content);
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -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));
|
||||
}
|
||||
|
||||
@@ -870,7 +906,7 @@ end`.replace(/\r?\n/g, " ");
|
||||
"_comment_warning": warning,
|
||||
...await this.resolveServerSettings(this.config.get("factorio.settings"), includeCredentials),
|
||||
};
|
||||
await lib.safeOutputFile(
|
||||
await lib.atomicOverwriteFile(
|
||||
this.server.writePath("server-settings.json"),
|
||||
JSON.stringify(serverSettings, null, "\t")
|
||||
);
|
||||
@@ -996,7 +1032,7 @@ end`.replace(/\r?\n/g, " ");
|
||||
|
||||
if (this.config.get("factorio.sync_adminlist") !== "disabled") {
|
||||
this.logger.verbose("Writing server-adminlist.json");
|
||||
await lib.safeOutputFile(
|
||||
await lib.atomicOverwriteFile(
|
||||
this.server.writePath("server-adminlist.json"),
|
||||
JSON.stringify([...this._host.adminlist], null, "\t")
|
||||
);
|
||||
@@ -1004,7 +1040,7 @@ end`.replace(/\r?\n/g, " ");
|
||||
|
||||
if (this.config.get("factorio.sync_banlist") !== "disabled") {
|
||||
this.logger.verbose("Writing server-banlist.json");
|
||||
await lib.safeOutputFile(
|
||||
await lib.atomicOverwriteFile(
|
||||
this.server.writePath("server-banlist.json"),
|
||||
JSON.stringify([...this._host.banlist].map(
|
||||
([username, reason]) => ({ username, reason })
|
||||
@@ -1014,7 +1050,7 @@ end`.replace(/\r?\n/g, " ");
|
||||
|
||||
if (this.config.get("factorio.sync_whitelist") !== "disabled") {
|
||||
this.logger.verbose("Writing server-whitelist.json");
|
||||
await lib.safeOutputFile(
|
||||
await lib.atomicOverwriteFile(
|
||||
this.server.writePath("server-whitelist.json"),
|
||||
JSON.stringify([...this._host.whitelist], null, "\t")
|
||||
);
|
||||
@@ -1032,6 +1068,39 @@ end`.replace(/\r?\n/g, " ");
|
||||
}
|
||||
|
||||
await this.syncMods();
|
||||
this.checkRequiredMods(this.activeModPack);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check that the mod pack has the mods required by the loaded plugins
|
||||
*
|
||||
* @throws {lib.ConflictError} if a required mod is missing, disabled or the wrong version.
|
||||
*/
|
||||
checkRequiredMods(modPack: lib.ModPack) {
|
||||
const problems = [];
|
||||
for (const pluginInfo of this.loadedPlugins) {
|
||||
const unmet = [];
|
||||
for (const dependency of lib.pluginRequiredMods(pluginInfo)) {
|
||||
const mod = modPack.mods.get(dependency.name);
|
||||
if (!mod) {
|
||||
unmet.push(`${dependency.spec} (missing)`);
|
||||
} else if (!mod.enabled) {
|
||||
unmet.push(`${dependency.spec} (disabled)`);
|
||||
} else if (dependency.version && !dependency.version.testVersion(mod.version)) {
|
||||
unmet.push(`${dependency.spec} (found ${mod.version})`);
|
||||
}
|
||||
}
|
||||
if (unmet.length) {
|
||||
problems.push(`Plugin ${pluginInfo.name} requires ${unmet.join(", ")}.`);
|
||||
}
|
||||
}
|
||||
if (problems.length) {
|
||||
throw new lib.ConflictError(
|
||||
`Mod pack ${modPack.name} does not have the mods required by the loaded plugins. ` +
|
||||
`${problems.join(" ")} ` +
|
||||
"Add the mods to the mod pack or set <plugin>.load_plugin to false for this instance."
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1082,6 +1151,9 @@ end`.replace(/\r?\n/g, " ");
|
||||
}
|
||||
|
||||
if (!this.config.get("factorio.enable_save_patching")) {
|
||||
if (await unpatch(this.path("saves", saveName))) {
|
||||
this.logger.info("Removed Clusterio modules from save as save patching is disabled");
|
||||
}
|
||||
return saveName;
|
||||
}
|
||||
|
||||
@@ -1308,10 +1380,21 @@ end`.replace(/\r?\n/g, " ");
|
||||
}
|
||||
}
|
||||
|
||||
/** Stop the instance once a start, stop or save in progress has finished */
|
||||
async _stopWhenSettled() {
|
||||
// Stopping concurrently with these races them and asserts on the server state.
|
||||
// Checked right before stop() as another waiter may have started stopping.
|
||||
while (transitoryStatuses.has(this._status)) {
|
||||
await this._waitForSettledStatus();
|
||||
}
|
||||
await this.stop();
|
||||
}
|
||||
|
||||
async kill() {
|
||||
if (this._status === "stopped") {
|
||||
return;
|
||||
}
|
||||
this._killRequested = true;
|
||||
await this.server.kill(true);
|
||||
}
|
||||
|
||||
@@ -1349,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);
|
||||
}
|
||||
@@ -1378,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");
|
||||
@@ -1494,7 +1582,7 @@ end`.replace(/\r?\n/g, " ");
|
||||
}
|
||||
|
||||
async handleInstanceRestartRequest(request: lib.InstanceRestartRequest) {
|
||||
await this.stop();
|
||||
await this._stopWhenSettled();
|
||||
// Stopping invalidates this instance object, a new one must be created by the host
|
||||
// To do this we simulate a waking an instance and sending a start request
|
||||
const instanceConnection = await this._host._connectInstance(this.id);
|
||||
@@ -1502,7 +1590,7 @@ end`.replace(/\r?\n/g, " ");
|
||||
}
|
||||
|
||||
async handleInstanceStopRequest() {
|
||||
await this.stop();
|
||||
await this._stopWhenSettled();
|
||||
}
|
||||
|
||||
async handleInstanceKillRequest() {
|
||||
|
||||
+118
-35
@@ -1,12 +1,16 @@
|
||||
// Export of item icons and locale
|
||||
import fs from "node:fs/promises";
|
||||
import path from "path";
|
||||
import { Jimp, JimpMime, type JimpInstance } from "jimp";
|
||||
import { createJimp } from "@jimp/core";
|
||||
import png from "@jimp/js-png";
|
||||
import * as crop from "@jimp/plugin-crop";
|
||||
import * as resize from "@jimp/plugin-resize";
|
||||
import type {} from "@jimp/types"; // needed to name jimp types in export.d.ts
|
||||
import yazl from "yazl";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import * as libBuildMod from "@clusterio/lib/dist/node/build_mod.js";
|
||||
import type { FactorioServer } from "./server.js";
|
||||
import { findVersion, isHeadless, type FactorioServer } from "./server.js";
|
||||
import { definesPrototypesFallback } from "./export_fallback.js";
|
||||
|
||||
interface SimpleIconSpecification {
|
||||
@@ -91,6 +95,16 @@ async function loadZip(server: FactorioServer, modVersions: Map<string, string>,
|
||||
return modZip;
|
||||
}
|
||||
|
||||
/** Where icon files are read from during an export. */
|
||||
interface ExportFiles {
|
||||
/** Mod zips opened during the export, closed when it ends. */
|
||||
zipCache: ZipCache;
|
||||
/** Data dir of a full install to fall back to for builtin mod files. */
|
||||
graphicsDataDir?: string;
|
||||
/** Why no full install was found for a headless server. */
|
||||
graphicsError?: string;
|
||||
}
|
||||
|
||||
function closeZipCache(zipCache: ZipCache) {
|
||||
for (const { zip } of zipCache.values()) {
|
||||
zip.close();
|
||||
@@ -103,7 +117,7 @@ function closeZipCache(zipCache: ZipCache) {
|
||||
*
|
||||
* @param server - The server to load the file from.
|
||||
* @param modVersions - Mapping of mod to version used.
|
||||
* @param zipCache - Mod zips opened by this export.
|
||||
* @param files - Where to read files from.
|
||||
* @param modPath - Factorio style path to the file to load.
|
||||
* @returns The content of the file or null if not found.
|
||||
* @internal
|
||||
@@ -111,7 +125,7 @@ function closeZipCache(zipCache: ZipCache) {
|
||||
async function loadFile(
|
||||
server: FactorioServer,
|
||||
modVersions: Map<string, string>,
|
||||
zipCache: ZipCache,
|
||||
files: ExportFiles,
|
||||
modPath: string,
|
||||
) {
|
||||
let match = /^__([^\/]+)__\/(.*)$/.exec(modPath);
|
||||
@@ -124,19 +138,25 @@ async function loadFile(
|
||||
|
||||
const builtinModNames = ["core", ...lib.ModPack.getBuiltinModNames(server.version!)];
|
||||
if (builtinModNames.includes(mod)) {
|
||||
try {
|
||||
return await fs.readFile(server.dataPath(mod, filePath));
|
||||
} catch (err: any) {
|
||||
if (err.code === "ENOENT") {
|
||||
return null;
|
||||
}
|
||||
throw err;
|
||||
const dataDirs = [server.dataPath()];
|
||||
if (files.graphicsDataDir) {
|
||||
dataDirs.push(files.graphicsDataDir);
|
||||
}
|
||||
for (const dataDir of dataDirs) {
|
||||
try {
|
||||
return await fs.readFile(path.join(dataDir, mod, filePath));
|
||||
} catch (err: any) {
|
||||
if (err.code !== "ENOENT") {
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
let modZip;
|
||||
try {
|
||||
modZip = await loadZip(server, modVersions, zipCache, mod);
|
||||
modZip = await loadZip(server, modVersions, files.zipCache, mod);
|
||||
} catch (err: any) {
|
||||
if (err.code === "ENOENT") {
|
||||
return null;
|
||||
@@ -147,12 +167,14 @@ async function loadFile(
|
||||
return await modZip.zip.readFile(path.posix.join(modZip.root, filePath));
|
||||
}
|
||||
|
||||
type Image = JimpInstance;
|
||||
// Only the parts of jimp the export uses
|
||||
const Jimp = createJimp({ formats: [png], plugins: [crop.methods, resize.methods] });
|
||||
type Image = InstanceType<typeof Jimp>;
|
||||
type IconCache = Map<string, Image | null>;
|
||||
async function loadIcon(
|
||||
server: FactorioServer,
|
||||
modVersions: Map<string, string>,
|
||||
zipCache: ZipCache,
|
||||
files: ExportFiles,
|
||||
iconPath: string,
|
||||
iconSize: number,
|
||||
iconMipmaps: number,
|
||||
@@ -160,7 +182,7 @@ async function loadIcon(
|
||||
) {
|
||||
let icon = iconCache.get(iconPath);
|
||||
if (icon === undefined) {
|
||||
let fileContent = await loadFile(server, modVersions, zipCache, iconPath);
|
||||
let fileContent = await loadFile(server, modVersions, files, iconPath);
|
||||
if (fileContent) {
|
||||
icon = await Jimp.fromBuffer(fileContent) as Image;
|
||||
icon.crop({ x: 0, y: 0, w: iconSize, h: iconSize });
|
||||
@@ -176,12 +198,12 @@ async function loadIcon(
|
||||
async function loadSimpleIcon(
|
||||
server: FactorioServer,
|
||||
modVersions: Map<string, string>,
|
||||
zipCache: ZipCache,
|
||||
files: ExportFiles,
|
||||
item: SimpleIconSpecification,
|
||||
size: number,
|
||||
iconCache: IconCache,
|
||||
): Promise<Image | null> {
|
||||
let icon = await loadIcon(server, modVersions, zipCache, item.icon, item.icon_size ?? 64, 0, iconCache);
|
||||
let icon = await loadIcon(server, modVersions, files, item.icon, item.icon_size ?? 64, 0, iconCache);
|
||||
if (icon) {
|
||||
let iconScale = size / (item.icon_size ?? 64);
|
||||
if (iconScale !== 1) {
|
||||
@@ -195,11 +217,11 @@ async function loadSimpleIcon(
|
||||
async function loadLayeredIcon(
|
||||
server: FactorioServer,
|
||||
modVersions: Map<string, string>,
|
||||
zipCache: ZipCache,
|
||||
files: ExportFiles,
|
||||
item: LayeredIconSpecification,
|
||||
size: number,
|
||||
iconCache: IconCache,
|
||||
): Promise<Image> {
|
||||
): Promise<Image | null> {
|
||||
let baseLayerSize = (item.icons[0].icon_size || item.icon_size) ?? 64;
|
||||
let icon = new Jimp({ width: size, height: size });
|
||||
|
||||
@@ -212,11 +234,12 @@ async function loadLayeredIcon(
|
||||
for (let layer of item.icons) {
|
||||
let layerSize = (layer.icon_size || item.icon_size) ?? 64;
|
||||
let iconLayer = await loadIcon(
|
||||
server, modVersions, zipCache, layer.icon, layerSize, layer.icon_mipmaps || 0, iconCache,
|
||||
server, modVersions, files, layer.icon, layerSize, layer.icon_mipmaps || 0, iconCache,
|
||||
);
|
||||
|
||||
// A partial icon would be wrong, skip it like a missing simple icon
|
||||
if (!iconLayer) {
|
||||
continue;
|
||||
return null;
|
||||
}
|
||||
|
||||
iconLayer = iconLayer.clone();
|
||||
@@ -331,7 +354,7 @@ async function growSheet(state: SheetState) {
|
||||
async function exportIcon(
|
||||
server: FactorioServer,
|
||||
modVersions: Map<string, string>,
|
||||
zipCache: ZipCache,
|
||||
files: ExportFiles,
|
||||
state: SheetState,
|
||||
prototype: PrototypeWithIcon,
|
||||
) {
|
||||
@@ -342,9 +365,11 @@ async function exportIcon(
|
||||
|
||||
if (prototype.icons) {
|
||||
icon = await loadLayeredIcon(
|
||||
server, modVersions, zipCache, prototype, SHEET_ICON_SIZE, state.iconCache,
|
||||
server, modVersions, files, prototype, SHEET_ICON_SIZE, state.iconCache,
|
||||
);
|
||||
iconPos = state.pos;
|
||||
if (icon) {
|
||||
iconPos = state.pos;
|
||||
}
|
||||
iconPath = prototype.icons[0].icon;
|
||||
|
||||
} else if (prototype.icon) {
|
||||
@@ -352,7 +377,7 @@ async function exportIcon(
|
||||
iconPath = prototype.icon;
|
||||
if (iconPos === undefined) {
|
||||
icon = await loadSimpleIcon(
|
||||
server, modVersions, zipCache, prototype, SHEET_ICON_SIZE, state.iconCache,
|
||||
server, modVersions, files, prototype, SHEET_ICON_SIZE, state.iconCache,
|
||||
);
|
||||
if (icon) {
|
||||
iconPos = state.pos;
|
||||
@@ -388,7 +413,7 @@ async function exportIcon(
|
||||
*
|
||||
* @param server - The server to load icons from.
|
||||
* @param modVersions - Mapping of mod name to version.
|
||||
* @param zipCache - Mod zips opened by this export.
|
||||
* @param files - Where to read icon files from.
|
||||
* @param prototypes - Array of prototypes with icon to export for this base type.
|
||||
* @param baseName - name of base type (used in metadata).
|
||||
* @param state - Shared spritesheet state (mutated in place).
|
||||
@@ -398,7 +423,7 @@ async function exportIcon(
|
||||
async function exportIcons(
|
||||
server: FactorioServer,
|
||||
modVersions: Map<string, string>,
|
||||
zipCache: ZipCache,
|
||||
files: ExportFiles,
|
||||
prototypes: PrototypeWithIcon[],
|
||||
baseName: string,
|
||||
state: SheetState,
|
||||
@@ -407,7 +432,13 @@ async function exportIcons(
|
||||
state.metadata[baseName] ??= metadata;
|
||||
let count = 0;
|
||||
for (let prototype of prototypes) {
|
||||
const icon = await exportIcon(server, modVersions, zipCache, state, prototype);
|
||||
let icon: lib.ExportMetadataEntry["icon"];
|
||||
try {
|
||||
icon = await exportIcon(server, modVersions, files, state, prototype);
|
||||
} catch (err: any) {
|
||||
// One broken icon should not stop the rest of the export
|
||||
server._logger.warn(`Skipping icon of ${prototype.type} ${prototype.name}: ${err.message}`);
|
||||
}
|
||||
if (icon) {
|
||||
count += 1;
|
||||
}
|
||||
@@ -478,6 +509,7 @@ async function exportLocale(
|
||||
modZip = await loadZip(server, modVersions, zipCache, mod);
|
||||
} catch (err: any) {
|
||||
if (err.code === "ENOENT") {
|
||||
server._logger.warn(`Skipping locale of ${mod}, its mod zip was not found`);
|
||||
continue;
|
||||
}
|
||||
throw err;
|
||||
@@ -497,20 +529,67 @@ async function exportLocale(
|
||||
/**
|
||||
* Export locale, icons and metadata for the given factorio server
|
||||
*
|
||||
* If the server runs the headless build, builtin mod graphics are read
|
||||
* from a full install of the same major and minor version found next to
|
||||
* it, if there is one.
|
||||
*
|
||||
* @param server - The server to export the data from.
|
||||
* @returns zip file with exported data.
|
||||
*/
|
||||
export async function exportData(server: FactorioServer) {
|
||||
const zipCache: ZipCache = new Map();
|
||||
const files: ExportFiles = { zipCache: new Map() };
|
||||
if (await isHeadless(server.dataPath())) {
|
||||
const majorMinor = server.version!.replace(/\.\d+$/, "") as lib.MajorMinorVersion;
|
||||
try {
|
||||
[files.graphicsDataDir] = await findVersion(server._factorioDir, majorMinor, false);
|
||||
} catch (err: any) {
|
||||
// Without it the export still has everything but the base game icons
|
||||
files.graphicsError = err.message;
|
||||
}
|
||||
}
|
||||
try {
|
||||
return await buildExport(server, zipCache);
|
||||
return await buildExport(server, files);
|
||||
} finally {
|
||||
// Free up the zip files loaded during the export.
|
||||
closeZipCache(zipCache);
|
||||
closeZipCache(files.zipCache);
|
||||
}
|
||||
}
|
||||
|
||||
async function buildExport(server: FactorioServer, zipCache: ZipCache) {
|
||||
/**
|
||||
* Warn if any builtin mod icon files could not be found
|
||||
*
|
||||
* @param server - The server the export ran on.
|
||||
* @param files - Where icon files were read from.
|
||||
* @param iconCache - Icons loaded by the export, null for missing files.
|
||||
* @internal
|
||||
*/
|
||||
function checkMissingBuiltinIcons(server: FactorioServer, files: ExportFiles, iconCache: IconCache) {
|
||||
const builtinModNames = ["core", ...lib.ModPack.getBuiltinModNames(server.version!)];
|
||||
let missing = 0;
|
||||
for (const [iconPath, icon] of iconCache) {
|
||||
const mod = /^__([^\/]+)__\//.exec(iconPath)?.[1];
|
||||
if (icon === null && mod && builtinModNames.includes(mod)) {
|
||||
missing += 1;
|
||||
}
|
||||
}
|
||||
if (!missing) {
|
||||
return;
|
||||
}
|
||||
|
||||
const dirs = [server.dataPath(), files.graphicsDataDir].filter(Boolean).join(" or ");
|
||||
let message =
|
||||
`${missing} icon files of the base game were not found in ${dirs}, icons using them were not exported.`;
|
||||
if (files.graphicsError !== undefined) {
|
||||
const majorMinor = server.version!.replace(/\.\d+$/, "");
|
||||
message +=
|
||||
` The headless build of Factorio has no graphics and no full install was found (${files.graphicsError}).` +
|
||||
` Add a full install of Factorio ${majorMinor} to host.factorio_directory to read them from there,` +
|
||||
" or export the data on a host with a full install.";
|
||||
}
|
||||
server._logger.warn(message);
|
||||
}
|
||||
|
||||
async function buildExport(server: FactorioServer, files: ExportFiles) {
|
||||
await generateExportMod(server);
|
||||
|
||||
let settings: lib.ExportSettings = {};
|
||||
@@ -590,7 +669,7 @@ async function buildExport(server: FactorioServer, zipCache: ZipCache) {
|
||||
}
|
||||
}
|
||||
|
||||
let locale = await exportLocale(server, modVersions, zipCache, modOrder, "en");
|
||||
let locale = await exportLocale(server, modVersions, files.zipCache, modOrder, "en");
|
||||
|
||||
let zip = new yazl.ZipFile();
|
||||
const addJson = (name: string, value: unknown) => zip.addBuffer(Buffer.from(JSON.stringify(value)), name);
|
||||
@@ -611,14 +690,15 @@ async function buildExport(server: FactorioServer, zipCache: ZipCache) {
|
||||
if (prototypesWithIcons.length === 0) {
|
||||
continue;
|
||||
}
|
||||
const count = await exportIcons(server, modVersions, zipCache, prototypesWithIcons, baseName, state);
|
||||
const count = await exportIcons(server, modVersions, files, prototypesWithIcons, baseName, state);
|
||||
server._logger.info(`Exported ${count} ${baseName} icons`);
|
||||
}
|
||||
checkMissingBuiltinIcons(server, files, state.iconCache);
|
||||
|
||||
// Crop sheet to actual used height and write single spritesheet + metadata.
|
||||
const usedRows = Math.ceil(state.pos / (SHEET_WIDTH / SHEET_ICON_SIZE));
|
||||
state.sheet.crop({ x: 0, y: 0, w: SHEET_WIDTH, h: Math.max(usedRows * SHEET_ICON_SIZE, 1) });
|
||||
zip.addBuffer(await state.sheet.getBuffer(JimpMime.png), "export/spritesheet.png");
|
||||
zip.addBuffer(await state.sheet.getBuffer("image/png"), "export/spritesheet.png");
|
||||
addJson("export/metadata.json", state.metadata satisfies lib.ExportMetadata);
|
||||
zip.end();
|
||||
|
||||
@@ -629,6 +709,9 @@ async function buildExport(server: FactorioServer, zipCache: ZipCache) {
|
||||
|
||||
|
||||
// For testing only
|
||||
export const _createSheetState = createSheetState;
|
||||
export const _exportIcons = exportIcons;
|
||||
export const _exportLocale = exportLocale;
|
||||
export const _loadSimpleIcon = loadSimpleIcon;
|
||||
export const _loadLayeredIcon = loadLayeredIcon;
|
||||
export const _checkMissingBuiltinIcons = checkMissingBuiltinIcons;
|
||||
@@ -0,0 +1,308 @@
|
||||
import { setTimeout as sleep } from "node:timers/promises";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import { logger } from "@clusterio/lib";
|
||||
|
||||
/** Time to wait for a response from the controller */
|
||||
const requestTimeoutMs = 30e3;
|
||||
/** Placeholder token of a host that has not been paired */
|
||||
const unpairedToken = "enter token here";
|
||||
|
||||
/** Error responded by the controller */
|
||||
export class PairingError extends Error {
|
||||
constructor(
|
||||
message: string,
|
||||
/** HTTP status the controller responded with */
|
||||
public status?: number,
|
||||
) {
|
||||
super(message);
|
||||
this.name = "PairingError";
|
||||
}
|
||||
}
|
||||
|
||||
export interface PairingResult {
|
||||
hostId: number;
|
||||
token: string;
|
||||
name: string;
|
||||
}
|
||||
|
||||
export interface PairHostOptions {
|
||||
/** URL of the controller, ending with a slash */
|
||||
controllerUrl: string;
|
||||
/** Name to request for the host */
|
||||
name: string;
|
||||
/** Version of the host, shown with the request */
|
||||
version?: string;
|
||||
/** Token of a user allowed to approve hosts, approves the host without waiting */
|
||||
token?: string;
|
||||
/** Interval to poll for the result at */
|
||||
pollIntervalMs?: number;
|
||||
/** Delay before trying again when the controller can't be reached or is busy */
|
||||
retryDelayMs?: number;
|
||||
/** Called with the code to approve the request with each time a request is made */
|
||||
onPending?: (code: string) => void;
|
||||
/** Called when the controller can't be reached or is busy and the request is retried */
|
||||
onRetry?: (err: Error, delayMs: number) => void;
|
||||
/** Signal to cancel pairing with */
|
||||
signal?: AbortSignal;
|
||||
}
|
||||
|
||||
interface Response {
|
||||
status: number;
|
||||
headers: Headers;
|
||||
json: any;
|
||||
}
|
||||
|
||||
async function request(
|
||||
controllerUrl: string,
|
||||
route: string,
|
||||
options: { body?: object, token?: string, signal?: AbortSignal, timeoutMs?: number },
|
||||
): Promise<Response> {
|
||||
const headers: Record<string, string> = { "Accept": "application/json" };
|
||||
if (options.body) {
|
||||
headers["Content-Type"] = "application/json";
|
||||
}
|
||||
if (options.token) {
|
||||
headers["Authorization"] = `Bearer ${options.token}`;
|
||||
}
|
||||
const timeout = AbortSignal.timeout(options.timeoutMs ?? requestTimeoutMs);
|
||||
const response = await fetch(new URL(route, controllerUrl), {
|
||||
method: options.body ? "POST" : "GET",
|
||||
headers,
|
||||
body: options.body ? JSON.stringify(options.body) : undefined,
|
||||
signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout,
|
||||
});
|
||||
let json;
|
||||
try {
|
||||
json = await response.json();
|
||||
} catch {
|
||||
json = undefined;
|
||||
}
|
||||
return { status: response.status, headers: response.headers, json };
|
||||
}
|
||||
|
||||
function responseError(response: Response) {
|
||||
const message = typeof response.json?.error === "string"
|
||||
? response.json.error
|
||||
: `Unexpected response from controller: ${response.status}`;
|
||||
return new PairingError(message, response.status);
|
||||
}
|
||||
|
||||
function pairingResult(response: Response): PairingResult {
|
||||
const { hostId, token, name } = response.json ?? {};
|
||||
if (!Number.isInteger(hostId) || typeof token !== "string" || typeof name !== "string") {
|
||||
throw new PairingError("Invalid response from controller", response.status);
|
||||
}
|
||||
return { hostId, token, name };
|
||||
}
|
||||
|
||||
/** Responses that are worth trying again later */
|
||||
function isTemporary(status: number) {
|
||||
return status === 429 || status >= 500;
|
||||
}
|
||||
|
||||
function retryDelay(response: Response, defaultMs: number) {
|
||||
const seconds = Number(response.headers.get("retry-after"));
|
||||
return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : defaultMs;
|
||||
}
|
||||
|
||||
/**
|
||||
* Poll a request until it is approved, rejected or no longer known by the controller
|
||||
*
|
||||
* @returns the result if approved, or null if the controller no longer knows the request.
|
||||
*/
|
||||
async function poll(
|
||||
requestId: string,
|
||||
options: Required<Pick<PairHostOptions, "pollIntervalMs" | "retryDelayMs">> & PairHostOptions,
|
||||
) {
|
||||
let delayMs = options.pollIntervalMs;
|
||||
while (true) {
|
||||
await sleep(delayMs, undefined, { signal: options.signal });
|
||||
delayMs = options.pollIntervalMs;
|
||||
let response;
|
||||
try {
|
||||
response = await request(options.controllerUrl, "api/host-pairing/poll", {
|
||||
body: { requestId }, signal: options.signal,
|
||||
});
|
||||
} catch (err: any) {
|
||||
if (options.signal?.aborted) {
|
||||
throw err;
|
||||
}
|
||||
// Keep polling through network errors, the request is made again if it expired meanwhile.
|
||||
delayMs = options.retryDelayMs;
|
||||
options.onRetry?.(err, delayMs);
|
||||
continue;
|
||||
}
|
||||
if (response.status === 200) {
|
||||
return pairingResult(response);
|
||||
}
|
||||
if (response.status === 404) {
|
||||
return null;
|
||||
}
|
||||
if (isTemporary(response.status)) {
|
||||
delayMs = retryDelay(response, options.retryDelayMs);
|
||||
options.onRetry?.(responseError(response), delayMs);
|
||||
continue;
|
||||
}
|
||||
if (response.status !== 202) {
|
||||
throw responseError(response);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Request to join the cluster and wait until the request is approved
|
||||
*
|
||||
* Waits through network errors and controller restarts, making a new request
|
||||
* if the controller no longer knows the previous one.
|
||||
*
|
||||
* @param options - Pairing options.
|
||||
* @returns id, token and approved name of the host.
|
||||
* @throws {PairingError} if the controller refuses or rejects the request.
|
||||
* @throws {DOMException} AbortError if the signal is aborted.
|
||||
*/
|
||||
export async function pairHost(options: PairHostOptions): Promise<PairingResult> {
|
||||
const opts = { pollIntervalMs: 2000, retryDelayMs: 10e3, version: "", ...options };
|
||||
let requestId: string | undefined;
|
||||
try {
|
||||
while (true) {
|
||||
opts.signal?.throwIfAborted();
|
||||
let response;
|
||||
try {
|
||||
response = await request(opts.controllerUrl, "api/host-pairing", {
|
||||
body: { name: opts.name, version: opts.version }, token: opts.token, signal: opts.signal,
|
||||
});
|
||||
} catch (err: any) {
|
||||
if (opts.signal?.aborted) {
|
||||
throw err;
|
||||
}
|
||||
opts.onRetry?.(err, opts.retryDelayMs);
|
||||
await sleep(opts.retryDelayMs, undefined, { signal: opts.signal });
|
||||
continue;
|
||||
}
|
||||
|
||||
if (response.status === 200) {
|
||||
return pairingResult(response);
|
||||
}
|
||||
if (isTemporary(response.status)) {
|
||||
const delayMs = retryDelay(response, opts.retryDelayMs);
|
||||
opts.onRetry?.(responseError(response), delayMs);
|
||||
await sleep(delayMs, undefined, { signal: opts.signal });
|
||||
continue;
|
||||
}
|
||||
if (response.status === 404) {
|
||||
throw new PairingError("The controller must be updated to a version that supports host pairing", 404);
|
||||
}
|
||||
if (response.status !== 202) {
|
||||
throw responseError(response);
|
||||
}
|
||||
if (typeof response.json?.requestId !== "string" || typeof response.json.code !== "string") {
|
||||
throw new PairingError("Invalid response from controller", response.status);
|
||||
}
|
||||
|
||||
requestId = response.json.requestId as string;
|
||||
opts.onPending?.(response.json.code);
|
||||
const result = await poll(requestId, opts);
|
||||
requestId = undefined;
|
||||
if (result) {
|
||||
return result;
|
||||
}
|
||||
}
|
||||
|
||||
} catch (err) {
|
||||
if (!opts.signal?.aborted) {
|
||||
throw err;
|
||||
}
|
||||
if (requestId !== undefined) {
|
||||
await request(opts.controllerUrl, "api/host-pairing/cancel", {
|
||||
body: { requestId }, timeoutMs: 5e3,
|
||||
}).catch(() => {});
|
||||
}
|
||||
throw new DOMException("Pairing was cancelled", "AbortError");
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if the controller accepts a host token
|
||||
*
|
||||
* @param controllerUrl - URL of the controller, ending with a slash.
|
||||
* @param token - Host token to check.
|
||||
* @param signal - Signal to cancel the check with.
|
||||
* @returns true if the token is valid and its host is registered.
|
||||
* @throws {PairingError} if the controller gives an unexpected response.
|
||||
*/
|
||||
export async function checkHostToken(controllerUrl: string, token: string, signal?: AbortSignal) {
|
||||
const response = await request(controllerUrl, "api/host-pairing/check", { token, signal });
|
||||
if (response.status === 200) {
|
||||
return true;
|
||||
}
|
||||
if (response.status === 401) {
|
||||
return false;
|
||||
}
|
||||
throw responseError(response);
|
||||
}
|
||||
|
||||
/**
|
||||
* Pair the host with the controller if it has not been paired, or the controller no longer accepts it
|
||||
*
|
||||
* Waits until the request is approved and saves the id, name and token of the host to its config.
|
||||
*
|
||||
* @param config - Config of the host.
|
||||
* @param options - Pairing options.
|
||||
* @throws {PairingError} if the controller refuses or rejects the request.
|
||||
* @throws {DOMException} AbortError if the signal is aborted.
|
||||
*/
|
||||
export async function ensurePaired(
|
||||
config: lib.HostConfig,
|
||||
options: { version: string, userToken?: string, signal?: AbortSignal },
|
||||
) {
|
||||
const controllerUrl = config.get("host.controller_url");
|
||||
const token = config.get("host.controller_token");
|
||||
if (token && token !== unpairedToken) {
|
||||
let valid;
|
||||
try {
|
||||
valid = await checkHostToken(controllerUrl, token, options.signal);
|
||||
} catch (err: any) {
|
||||
if (options.signal?.aborted) {
|
||||
throw err;
|
||||
}
|
||||
// Connecting reports the problem, or authenticates if the controller predates pairing.
|
||||
logger.verbose(`Unable to check if the controller accepts this host: ${err.message}`);
|
||||
return;
|
||||
}
|
||||
if (valid) {
|
||||
return;
|
||||
}
|
||||
logger.warn("The controller no longer accepts this host, requesting to join again");
|
||||
}
|
||||
|
||||
const name = config.get("host.name");
|
||||
logger.info(`Requesting to join the cluster at ${controllerUrl} as "${name}"`);
|
||||
const result = await pairHost({
|
||||
controllerUrl,
|
||||
name,
|
||||
version: options.version,
|
||||
token: options.userToken,
|
||||
signal: options.signal,
|
||||
onPending: code => {
|
||||
const approveUrl = new URL(`hosts?approve=${code}`, controllerUrl).href;
|
||||
// Logged as warnings for the systemd service, which only prints warnings and above.
|
||||
// The link is logged on its own so terminals can make it clickable without it wrapping.
|
||||
logger.warn(`Waiting for approval of "${name}" with code ${code}, open this link to approve it:`);
|
||||
logger.warn(approveUrl);
|
||||
logger.warn(`Or run: npx clusterioctl host approve ${code}`);
|
||||
},
|
||||
onRetry: (err, delayMs) => {
|
||||
logger.warn(`Requesting to join failed: ${err.message}, trying again in ${Math.ceil(delayMs / 1000)}s`);
|
||||
},
|
||||
});
|
||||
|
||||
// The host has not started yet, so the new token needs no restart.
|
||||
const restartRequired = config.restartRequired;
|
||||
config.set("host.id", result.hostId);
|
||||
config.set("host.name", result.name);
|
||||
config.set("host.controller_token", result.token);
|
||||
config.restartRequired = restartRequired;
|
||||
await config.save();
|
||||
logger.info(`Host approved as "${result.name}" with id ${result.hostId}`);
|
||||
}
|
||||
+130
-48
@@ -227,6 +227,7 @@ export class PatchInfo {
|
||||
json.patch_number,
|
||||
lib.ModuleInfo.fromJSON(json.scenario),
|
||||
await Promise.all(json.modules.map(m => SaveModule.fromSave(m, zip, root))),
|
||||
json.version,
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -381,6 +382,72 @@ const knownScenarios: Record<string, lib.ModuleInfo> = {
|
||||
"3af547d2f4db3728b75ac5d1b3a4f47830dc48e7": new lib.ModuleInfo("freeplay", "2.0.29", [], ["scenario"]),
|
||||
};
|
||||
|
||||
/**
|
||||
* Names of the zip entries added by patching for the modules in the patch info
|
||||
*/
|
||||
function moduleEntries(zip: lib.ZipArchive, patchInfo: PatchInfo, root: string) {
|
||||
const entries = new Set<string>();
|
||||
if (patchInfo.version === 0) {
|
||||
const modulesPath = path.posix.join(root, "modules/");
|
||||
for (const name of zip.entries.keys()) {
|
||||
if (name.startsWith(modulesPath)) {
|
||||
entries.add(name);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
for (const module of patchInfo.modules) {
|
||||
for (const filepath of module.files.keys()) {
|
||||
entries.add(path.posix.join(root, filepath));
|
||||
}
|
||||
}
|
||||
}
|
||||
return entries;
|
||||
}
|
||||
|
||||
/**
|
||||
* Write a copy of the save next to it with entries removed and added
|
||||
*
|
||||
* Keeps the order of the entries in the original.
|
||||
*
|
||||
* @returns Path to the temporary file written.
|
||||
*/
|
||||
async function rewriteSave(
|
||||
zip: lib.ZipArchive, savePath: string, removed: Set<string>, added: Map<string, Buffer>
|
||||
) {
|
||||
added = new Map(added);
|
||||
const output = new lib.ZipWriter();
|
||||
const [tempSavePath, writeStream] = await lib.createTempWriteStream(savePath);
|
||||
const writing = pipeline(output.outputStream, writeStream);
|
||||
// Awaited below, but a write error can reject it before then.
|
||||
writing.catch(() => {});
|
||||
try {
|
||||
for (const entry of zip.entries.values()) {
|
||||
const name = entry.fileName;
|
||||
if (removed.has(name)) {
|
||||
continue;
|
||||
}
|
||||
const contents = added.get(name);
|
||||
if (contents !== undefined) {
|
||||
await output.addBuffer(contents, name);
|
||||
added.delete(name);
|
||||
} else {
|
||||
await output.addEntry(zip, entry);
|
||||
}
|
||||
}
|
||||
for (const [name, contents] of added) {
|
||||
await output.addBuffer(contents, name);
|
||||
}
|
||||
await output.end();
|
||||
await writing;
|
||||
} catch (err) {
|
||||
output.outputStream.destroy();
|
||||
await writing.catch(() => {});
|
||||
await fs.rm(tempSavePath, { force: true });
|
||||
throw err;
|
||||
}
|
||||
return tempSavePath;
|
||||
}
|
||||
|
||||
/**
|
||||
* Patch a save with the given modules
|
||||
*
|
||||
@@ -412,6 +479,16 @@ export async function patch(savePath: string, modules: SaveModule[]) {
|
||||
);
|
||||
}
|
||||
|
||||
// Unpatching put the original control.lua back in place of scenario.lua
|
||||
const scenarioRequired = [...patchInfo.scenario.load, ...patchInfo.scenario.require].includes("scenario");
|
||||
if (scenarioRequired && !zip.file(rootPath("scenario.lua"))) {
|
||||
const control = await zip.readFile(rootPath("control.lua"));
|
||||
if (control === null) {
|
||||
throw new Error("Unable to patch save, missing control.lua file.");
|
||||
}
|
||||
files.set("scenario.lua", control);
|
||||
}
|
||||
|
||||
// No info file present, try to detect if it's a known compatible scenario.
|
||||
} else {
|
||||
const controlFile = zip.file(rootPath("control.lua"));
|
||||
@@ -432,22 +509,8 @@ export async function patch(savePath: string, modules: SaveModule[]) {
|
||||
patchInfo.patchNumber = patchInfo.patchNumber + 1;
|
||||
|
||||
// Remove any existing modules from the save
|
||||
const removed = new Set<string>();
|
||||
if (patchInfo.version === 0) {
|
||||
const modulesPath = rootPath("modules/");
|
||||
for (const name of zip.entries.keys()) {
|
||||
if (name.startsWith(modulesPath)) {
|
||||
removed.add(name);
|
||||
}
|
||||
}
|
||||
} else {
|
||||
for (const module of patchInfo.modules) {
|
||||
for (const filepath of module.files.keys()) {
|
||||
removed.add(rootPath(filepath));
|
||||
}
|
||||
}
|
||||
patchInfo.modules = [];
|
||||
}
|
||||
const removed = moduleEntries(zip, patchInfo, root);
|
||||
patchInfo.modules = [];
|
||||
|
||||
reorderDependencies(modules);
|
||||
|
||||
@@ -463,45 +526,64 @@ export async function patch(savePath: string, modules: SaveModule[]) {
|
||||
files.set("control.lua", Buffer.from(generateLoader(patchInfo), "utf8"));
|
||||
files.set("clusterio.json", Buffer.from(JSON.stringify(patchInfo, null, "\t"), "utf8"));
|
||||
|
||||
// Write back the save, keeping the order of the entries in the original
|
||||
const added = new Map([...files].map(([relativePath, contents]) => [rootPath(relativePath), contents]));
|
||||
const output = new lib.ZipWriter();
|
||||
let writeStream;
|
||||
[tempSavePath, writeStream] = await lib.createTempWriteStream(savePath);
|
||||
const writing = pipeline(output.outputStream, writeStream);
|
||||
// Awaited below, but a write error can reject it before then.
|
||||
writing.catch(() => {});
|
||||
try {
|
||||
for (const entry of zip.entries.values()) {
|
||||
const name = entry.fileName;
|
||||
if (removed.has(name)) {
|
||||
continue;
|
||||
}
|
||||
const contents = added.get(name);
|
||||
if (contents !== undefined) {
|
||||
await output.addBuffer(contents, name);
|
||||
added.delete(name);
|
||||
} else {
|
||||
await output.addEntry(zip, entry);
|
||||
}
|
||||
}
|
||||
for (const [name, contents] of added) {
|
||||
await output.addBuffer(contents, name);
|
||||
}
|
||||
await output.end();
|
||||
await writing;
|
||||
} catch (err) {
|
||||
output.outputStream.destroy();
|
||||
await writing.catch(() => {});
|
||||
await fs.rm(tempSavePath, { force: true });
|
||||
throw err;
|
||||
}
|
||||
tempSavePath = await rewriteSave(zip, savePath, removed, added);
|
||||
} finally {
|
||||
zip.close();
|
||||
}
|
||||
await fs.rename(tempSavePath, savePath);
|
||||
}
|
||||
|
||||
/**
|
||||
* Remove the modules patched into a save
|
||||
*
|
||||
* Moves the original control.lua that patching kept as scenario.lua back
|
||||
* and removes the module files. The patch info is kept with no modules so that
|
||||
* the patch number keeps counting if the save is patched again.
|
||||
*
|
||||
* @param savePath - Path to the Factorio save to unpatch.
|
||||
* @returns true if the save was changed.
|
||||
*/
|
||||
export async function unpatch(savePath: string) {
|
||||
const zip = await lib.ZipArchive.fromFile(savePath);
|
||||
let tempSavePath: string;
|
||||
try {
|
||||
const root = lib.findRoot(zip);
|
||||
const rootPath = (relativePath: string) => path.posix.join(root, relativePath);
|
||||
const patchInfoContent = await zip.readFile(rootPath("clusterio.json"));
|
||||
if (patchInfoContent === null) {
|
||||
return false;
|
||||
}
|
||||
const patchInfo = await PatchInfo.fromSave(JSON.parse(patchInfoContent.toString("utf8")), zip, root);
|
||||
if (patchInfo.version > PatchInfo.currentVersion) {
|
||||
throw new Error(
|
||||
`Save patch version ${patchInfo.version} is newer than the patch version this ` +
|
||||
`version of Clusterio can unpatch (${PatchInfo.currentVersion})`
|
||||
);
|
||||
}
|
||||
if (patchInfo.version !== 0 && !patchInfo.modules.length) {
|
||||
return false;
|
||||
}
|
||||
|
||||
const removed = moduleEntries(zip, patchInfo, root);
|
||||
patchInfo.modules = [];
|
||||
const scenario = await zip.readFile(rootPath("scenario.lua"));
|
||||
if (scenario !== null) {
|
||||
removed.add(rootPath("scenario.lua"));
|
||||
}
|
||||
// Scenarios made for Clusterio have no scenario.lua, keep loading them without modules
|
||||
const control = scenario ?? Buffer.from(generateLoader(patchInfo), "utf8");
|
||||
tempSavePath = await rewriteSave(zip, savePath, removed, new Map([
|
||||
[rootPath("control.lua"), control],
|
||||
[rootPath("clusterio.json"), Buffer.from(JSON.stringify(patchInfo, null, "\t"), "utf8")],
|
||||
]));
|
||||
} finally {
|
||||
zip.close();
|
||||
}
|
||||
await fs.rename(tempSavePath, savePath);
|
||||
return true;
|
||||
}
|
||||
|
||||
// For testing only
|
||||
export const _generateLoader = generateLoader;
|
||||
export const _reorderDependencies = reorderDependencies;
|
||||
+82
-15
@@ -1,6 +1,6 @@
|
||||
// Factorio Server interface
|
||||
import fs from "node:fs/promises";
|
||||
import { type FSWatcher, createWriteStream, watch as fsWatch, writeFileSync } from "node:fs";
|
||||
import { type FSWatcher, createWriteStream, existsSync, watch as fsWatch, writeFileSync } from "node:fs";
|
||||
import child_process from "child_process";
|
||||
import dgram from "dgram";
|
||||
import path from "path";
|
||||
@@ -182,6 +182,15 @@ async function downloadAndExtractTar(url: string, targetDir: string) {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Factorio Linux build architecture matching this host
|
||||
*
|
||||
* @returns "arm64" on ARM64 Linux, otherwise "x64".
|
||||
*/
|
||||
function factorioArch(): lib.FactorioHeadlessArch {
|
||||
return process.platform === "linux" && process.arch === "arm64" ? "arm64" : "x64";
|
||||
}
|
||||
|
||||
// Factorio downloads in progress by target directory, shared by every server in the process
|
||||
const downloadsInProgress = new Map<string, Promise<void>>();
|
||||
|
||||
@@ -202,14 +211,27 @@ export async function checkForUpdates(
|
||||
logger: lib.Logger = lib.logger,
|
||||
) {
|
||||
|
||||
const latestVersion = availableVersions
|
||||
.filter(v => (
|
||||
targetVersion === "latest" || v.version === targetVersion || v.version.startsWith(targetVersion)
|
||||
))
|
||||
const matchesTarget = (version: string) => (
|
||||
targetVersion === "latest" || version === targetVersion || version.startsWith(targetVersion)
|
||||
);
|
||||
const arch = factorioArch();
|
||||
const matching = availableVersions.filter(v => matchesTarget(v.version));
|
||||
const latestVersion = matching
|
||||
.filter(v => process.platform !== "linux" || lib.hasFactorioHeadless(v.version, "linux", arch))
|
||||
.sort((v1, v2) => versionOrder(v1.version, v2.version))
|
||||
[0];
|
||||
|
||||
if (!latestVersion) {
|
||||
if (matching.length && arch === "arm64" && process.platform === "linux") {
|
||||
const installed = await listFactorioVersions(factorioDir);
|
||||
if (!installed.direct && ![...installed.versions].some(matchesTarget)) {
|
||||
throw new Error(
|
||||
`Factorio ${targetVersion} has no ARM64 Linux headless build to download, ` +
|
||||
`ARM64 builds start at ${lib.minimumArm64HeadlessVersion}. Install it manually ` +
|
||||
`or use version ${lib.minimumArm64HeadlessVersion} or later.`
|
||||
);
|
||||
}
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -242,7 +264,7 @@ export async function checkForUpdates(
|
||||
logger.info(`A newer version of factorio is available (${v}), waiting for download...`);
|
||||
} else {
|
||||
logger.info(`A newer version of factorio is available (${v}), starting download...`);
|
||||
download = downloadAndExtractTar(latestVersion.headlessUrl, dst).finally(() => {
|
||||
download = downloadAndExtractTar(lib.factorioHeadlessUrl(v, "linux", arch), dst).finally(() => {
|
||||
downloadsInProgress.delete(dst);
|
||||
});
|
||||
downloadsInProgress.set(dst, download);
|
||||
@@ -262,15 +284,33 @@ export async function checkForUpdates(
|
||||
* @param targetVersion -
|
||||
* Version to look for, supports the special value "latest" for the
|
||||
* latest version available.
|
||||
* @param headless -
|
||||
* Only consider headless installs if true, or only full installs if
|
||||
* false.
|
||||
* @returns Array with path to data dir and version found.
|
||||
*/
|
||||
export async function findVersion(
|
||||
factorioDir: string,
|
||||
targetVersion: lib.TargetVersion,
|
||||
headless?: boolean,
|
||||
): Promise<[string, lib.FullVersion]> {
|
||||
let kind = "";
|
||||
if (headless !== undefined) {
|
||||
kind = headless ? "headless " : "full ";
|
||||
}
|
||||
const checkInstallType = async (dir: string) => (
|
||||
headless === undefined || await isHeadless(path.join(dir, "data")) === headless
|
||||
);
|
||||
|
||||
// Check if this is a direct installation dir
|
||||
const directVersion = await getFactorioVersion(factorioDir);
|
||||
if (directVersion !== null) {
|
||||
if (!await checkInstallType(factorioDir)) {
|
||||
throw new Error(
|
||||
`Unable to find a ${kind}install of Factorio ${targetVersion}: ${factorioDir} is a direct ` +
|
||||
`(single-version) install of the ${headless ? "full" : "headless"} build.`
|
||||
);
|
||||
}
|
||||
if (targetVersion === "latest" || directVersion === targetVersion || directVersion.startsWith(targetVersion)) {
|
||||
return [path.join(factorioDir, "data"), directVersion];
|
||||
}
|
||||
@@ -287,7 +327,7 @@ export async function findVersion(
|
||||
// Avoid any fancy directory detection in order to follow symlinks
|
||||
const fullPath = path.join(factorioDir, name);
|
||||
const version = await getFactorioVersion(fullPath);
|
||||
if (version === null) {
|
||||
if (version === null || !await checkInstallType(fullPath)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
@@ -299,7 +339,7 @@ export async function findVersion(
|
||||
}
|
||||
|
||||
if (!versions.size) {
|
||||
throw new Error(`Unable to find any Factorio install in ${factorioDir}`);
|
||||
throw new Error(`Unable to find any ${kind}Factorio install in ${factorioDir}`);
|
||||
}
|
||||
|
||||
if (lib.isPartialVersion(targetVersion)) {
|
||||
@@ -315,7 +355,26 @@ export async function findVersion(
|
||||
return [path.join(factorioDir, versions.get(latest)!, "data"), latest];
|
||||
}
|
||||
|
||||
throw new Error(`Unable to find Factorio version ${targetVersion}`);
|
||||
throw new Error(`Unable to find ${kind}Factorio version ${targetVersion}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check if a Factorio install is the headless build
|
||||
*
|
||||
* The headless build has no icons, which is what tells it apart.
|
||||
*
|
||||
* @param dataDir - Path to the data dir of the install.
|
||||
*/
|
||||
export async function isHeadless(dataDir: string) {
|
||||
try {
|
||||
await fs.access(path.join(dataDir, "base", "graphics", "icons"));
|
||||
return false;
|
||||
} catch (err: any) {
|
||||
if (err.code === "ENOENT" || err.code === "ENOTDIR") {
|
||||
return true;
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -1118,9 +1177,8 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
|
||||
}
|
||||
|
||||
const newWhitelist = new Set(newWhitelistJson);
|
||||
// Set.difference added in node v22 and so we can not use this due to v20 support
|
||||
const added = newWhitelistJson.filter(e => !this._whitelist.has(e));
|
||||
const removed = [...this._whitelist.values()].filter(e => !newWhitelist.has(e));
|
||||
const added = [...newWhitelist.difference(this._whitelist)];
|
||||
const removed = [...this._whitelist.difference(newWhitelist)];
|
||||
this._whitelist = newWhitelist;
|
||||
|
||||
this.emit("whitelist-change", added, removed);
|
||||
@@ -1698,8 +1756,8 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
|
||||
/**
|
||||
* Get Factorio binary path
|
||||
*
|
||||
* Get the path to the factorio binary depending on the configuration
|
||||
* and or the platform (MacOS support)
|
||||
* Get the path to the factorio binary depending on the configuration,
|
||||
* the platform (MacOS support) and the bin/x64 or bin/arm64 dir present
|
||||
*
|
||||
* @returns Path to factorio binary
|
||||
*/
|
||||
@@ -1710,7 +1768,16 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
|
||||
if (process.platform === "darwin") {
|
||||
return this.dataPath("..", "MacOS", "factorio");
|
||||
}
|
||||
return this.dataPath("..", "bin", "x64", "factorio");
|
||||
// Prefer the native build, fall back to whichever one is installed
|
||||
const arches = factorioArch() === "arm64" ? ["arm64", "x64"] : ["x64", "arm64"];
|
||||
for (const arch of arches) {
|
||||
const binary = this.dataPath("..", "bin", arch, "factorio");
|
||||
// eslint-disable-next-line node/no-sync
|
||||
if (existsSync(binary)) {
|
||||
return binary;
|
||||
}
|
||||
}
|
||||
return this.dataPath("..", "bin", arches[0], "factorio");
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -0,0 +1,3 @@
|
||||
// This needs to be a separate file due to ECMAScript Modules evaluating code in
|
||||
// imported modules before any code in the file that imports it.
|
||||
(global as any).lazySchemaCompilation = true;
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"entryPoints": ["index.ts"],
|
||||
"includeVersion": true
|
||||
}
|
||||
@@ -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";
|
||||
|
||||
|
||||
@@ -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";
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@clusterio/lib",
|
||||
"version": "2.0.3",
|
||||
"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",
|
||||
@@ -46,16 +60,14 @@
|
||||
"compile_validator": "node scripts/compile_validator.js"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=22"
|
||||
"node": "^22.18.0 || >=24.2.0"
|
||||
},
|
||||
|
||||
"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:"
|
||||
}
|
||||
}
|
||||
@@ -3,7 +3,9 @@ import path from "path";
|
||||
import events from "events";
|
||||
import { Static } from "@sinclair/typebox";
|
||||
import { logger } from "./logging.js";
|
||||
import { downloadFile, safeOutputFile } from "./file_ops.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}.`);
|
||||
}
|
||||
@@ -148,7 +186,7 @@ export default class ModStore extends events.EventEmitter<ModStoreEvents> {
|
||||
if (files.size) {
|
||||
logger.info(`Loaded info for ${files.size} mods`);
|
||||
const content: ModInfoCache = [...files.values()].map(mod => mod.toJSON());
|
||||
await safeOutputFile(cacheFilename, JSON.stringify(content));
|
||||
await atomicOverwriteFile(cacheFilename, JSON.stringify(content));
|
||||
}
|
||||
|
||||
return new this(modsDirectory, files);
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
@@ -7,7 +7,7 @@ import isDeepStrictEqual from "#is_deep_strict_equal";
|
||||
import { basicType } from "../helpers.js";
|
||||
import * as libSchema from "../schema.js";
|
||||
import { StringEnum } from "../data/composites.js";
|
||||
import { safeOutputFile } from "../file_ops.js";
|
||||
import { atomicOverwriteFile } from "../file_ops.js";
|
||||
import * as validators from "./validators.js";
|
||||
import { InvalidAccessError, InvalidFieldError, InvalidValueError } from "../errors.js";
|
||||
import type { SyncHook } from "../SyncHook.js";
|
||||
@@ -88,10 +88,11 @@ export interface FieldDefinition<
|
||||
optional?: Type extends null ? true : false;
|
||||
/**
|
||||
* Value this config field should take in a newly initialized config.
|
||||
* This can also be a synchronous function returning the value to use.
|
||||
* This can also be a synchronous function returning the value to use,
|
||||
* it is called after the stored fields are loaded so that it can read them.
|
||||
* Promise results are not awaited.
|
||||
*/
|
||||
initialValue?: unknown | (() => unknown);
|
||||
initialValue?: unknown | ((config: Config<Fields>) => unknown);
|
||||
/**
|
||||
* Array of all values that are acceptible. Useful for making
|
||||
* enumerated values.
|
||||
@@ -140,9 +141,6 @@ function defaultValue(def: FieldDefinition) {
|
||||
if (def.initialValue === undefined) {
|
||||
return null;
|
||||
}
|
||||
if (typeof def.initialValue === "function") {
|
||||
return def.initialValue();
|
||||
}
|
||||
return def.initialValue;
|
||||
}
|
||||
|
||||
@@ -246,14 +244,12 @@ export class Config<
|
||||
}
|
||||
super();
|
||||
|
||||
const defs = Object.entries(this.constructor.fieldDefinitions).filter(
|
||||
([name, def]) => this._checkAccess(name, def, location, ConfigAccess.read, false)
|
||||
);
|
||||
// Function initial values are left undefined until the stored fields are loaded
|
||||
this.fields = Object.fromEntries(
|
||||
Object.entries(
|
||||
this.constructor.fieldDefinitions
|
||||
).filter(
|
||||
([name, def]) => this._checkAccess(name, def, location, ConfigAccess.read, false)
|
||||
).map(
|
||||
([name, def]) => [name, defaultValue(def)]
|
||||
)
|
||||
defs.map(([name, def]) => [name, typeof def.initialValue === "function" ? undefined : defaultValue(def)])
|
||||
) as Fields;
|
||||
|
||||
if (fields) {
|
||||
@@ -264,6 +260,12 @@ export class Config<
|
||||
this.update(migrated, false, location);
|
||||
}
|
||||
|
||||
for (const [name, def] of defs) {
|
||||
if (this.fields[name as keyof Fields] === undefined) {
|
||||
this.fields[name as keyof Fields] = (def.initialValue as (config: Config<Fields>) => any)(this);
|
||||
}
|
||||
}
|
||||
|
||||
for (const [pluginName, version] of this.constructor.pluginVersions) {
|
||||
const name = `${pluginName}.version` as keyof Fields & string;
|
||||
if (name in this.fields && this.fields[name] !== version) {
|
||||
@@ -475,7 +477,7 @@ export class Config<
|
||||
if (!this.filepath) {
|
||||
throw new Error("Cannot save config which has no filepath");
|
||||
}
|
||||
await safeOutputFile(this.filepath, JSON.stringify(this, null, "\t"), { mode: 0o600 });
|
||||
await atomicOverwriteFile(this.filepath, JSON.stringify(this, null, "\t"), { mode: 0o600 });
|
||||
this._dirty = false;
|
||||
}
|
||||
|
||||
|
||||
@@ -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,12 +32,16 @@ export interface ControllerConfigFields {
|
||||
"controller.max_subscription_filters": number;
|
||||
"controller.system_metrics_interval": number;
|
||||
"controller.proxy_stream_timeout": number;
|
||||
"controller.transfer_min_speed": number;
|
||||
"controller.factorio_username": string | null;
|
||||
"controller.factorio_token": string | null;
|
||||
"controller.share_factorio_credentials_with_hosts": boolean;
|
||||
"controller.default_mod_pack_id": number | null;
|
||||
"controller.default_role_id": number | null;
|
||||
"controller.autosave_interval": number;
|
||||
"controller.log_retention_days": number;
|
||||
"controller.host_pairing_timeout": number;
|
||||
"controller.host_pairing_max_pending": number;
|
||||
"controller.mod_portal_cache_duration_minutes": number;
|
||||
"controller.mod_portal_page_size": number;
|
||||
"controller.allow_remote_updates": boolean;
|
||||
@@ -59,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;
|
||||
}
|
||||
@@ -98,6 +111,27 @@ export class ControllerConfig extends classes.Config<ControllerConfigFields> {
|
||||
initialValue: 60,
|
||||
validator: validators.greaterThanZero,
|
||||
},
|
||||
"controller.log_retention_days": {
|
||||
title: "Log Retention Days",
|
||||
description: "Days to keep controller and cluster log files for, 0 to keep them forever.",
|
||||
type: "number",
|
||||
initialValue: 30,
|
||||
validator: validators.all(validators.integer, validators.greaterThanEqualZero),
|
||||
},
|
||||
"controller.host_pairing_timeout": {
|
||||
title: "Host Pairing Timeout",
|
||||
description: "Time in seconds a host can wait for approval before it has to request again, 0 for no limit.",
|
||||
type: "number",
|
||||
initialValue: 3600,
|
||||
validator: validators.greaterThanEqualZero,
|
||||
},
|
||||
"controller.host_pairing_max_pending": {
|
||||
title: "Host Pairing Max Pending",
|
||||
description: "Maximum number of hosts that can wait for approval at the same time, 0 for no limit.",
|
||||
type: "number",
|
||||
initialValue: 50,
|
||||
validator: validators.all(validators.integer, validators.greaterThanEqualZero),
|
||||
},
|
||||
"controller.http_port": {
|
||||
title: "HTTP Port",
|
||||
description: "Port to listen for HTTP connections on, set to null to not listen for HTTP connections.",
|
||||
@@ -144,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/)",
|
||||
@@ -199,6 +239,13 @@ export class ControllerConfig extends classes.Config<ControllerConfigFields> {
|
||||
initialValue: 15,
|
||||
validator: validators.greaterThanZero,
|
||||
},
|
||||
"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: 64,
|
||||
validator: validators.greaterThanEqualZero,
|
||||
},
|
||||
"controller.session_timeout": {
|
||||
title: "Session Timeout",
|
||||
description: "Time in seconds before giving up resuming a dropped WebSocket session.",
|
||||
@@ -333,6 +380,7 @@ export interface HostConfigFields {
|
||||
"host.factorio_username": string | null,
|
||||
"host.factorio_token": string | null,
|
||||
"host.max_reconnect_delay": number;
|
||||
"host.log_retention_days": number;
|
||||
"host.allow_remote_updates": boolean;
|
||||
"host.allow_plugin_updates": boolean;
|
||||
"host.allow_plugin_install": boolean;
|
||||
@@ -442,6 +490,13 @@ export class HostConfig extends classes.Config<HostConfigFields> {
|
||||
initialValue: 60,
|
||||
validator: validators.greaterThanZero,
|
||||
},
|
||||
"host.log_retention_days": {
|
||||
title: "Log Retention Days",
|
||||
description: "Days to keep host log files for, 0 to keep them forever.",
|
||||
type: "number",
|
||||
initialValue: 30,
|
||||
validator: validators.all(validators.integer, validators.greaterThanEqualZero),
|
||||
},
|
||||
"host.allow_remote_updates": {
|
||||
description: "When true, allows a remote event to trigger a clusterio update via npm",
|
||||
type: "boolean",
|
||||
@@ -472,6 +527,11 @@ 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[]>;
|
||||
[key: `${string}.load_plugin`]: boolean;
|
||||
[key: `${string}.version`]: string;
|
||||
|
||||
@@ -523,6 +583,38 @@ export class InstanceConfig extends classes.Config<InstanceConfigFields> {
|
||||
return config;
|
||||
}
|
||||
|
||||
/** Fields that are never inherited from a template, ports clash on a shared host and secrets stay per instance */
|
||||
static uninheritableFields = [
|
||||
"instance.name", "instance.is_template", "instance.template_id",
|
||||
"factorio.game_port", "factorio.rcon_port", "factorio.rcon_password", "factorio.lua_udp_port",
|
||||
];
|
||||
|
||||
/** True if the field can take its value from a template */
|
||||
static isInheritable(name: string) {
|
||||
const def = this.fieldDefinitions[name as keyof InstanceConfigFields];
|
||||
return Boolean(def)
|
||||
&& !def.hidden
|
||||
&& (def.access ?? this.defaultAccess).includes("controller")
|
||||
&& !this.uninheritableFields.includes(name);
|
||||
}
|
||||
|
||||
/**
|
||||
* True if the field, or the given property of an object field, takes its value from the template
|
||||
*
|
||||
* @param name - Name of field to check.
|
||||
* @param prop - Property of an object field to check.
|
||||
*/
|
||||
isInherited(name: string, prop?: string) {
|
||||
if (this.get("instance.template_id") === null) {
|
||||
return false;
|
||||
}
|
||||
const entry = this.get("instance.inherited_fields")[name];
|
||||
if (entry instanceof Array) {
|
||||
return prop === undefined || !entry.includes(prop);
|
||||
}
|
||||
return Boolean(entry);
|
||||
}
|
||||
|
||||
static fieldDefinitions: classes.ConfigDefs<InstanceConfigFields> = {
|
||||
"instance.name": {
|
||||
type: "string",
|
||||
@@ -550,6 +642,43 @@ 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. " +
|
||||
"Templates cannot be assigned to a host or started.",
|
||||
access: ["controller", "control"],
|
||||
type: "boolean",
|
||||
initialValue: false,
|
||||
hidden: true,
|
||||
},
|
||||
"instance.template_id": {
|
||||
title: "Template",
|
||||
description: "ID of the template to inherit config values from",
|
||||
access: ["controller", "control"],
|
||||
inputComponent: "instance_template",
|
||||
type: "number",
|
||||
optional: true,
|
||||
// Checked by the controller
|
||||
},
|
||||
"instance.inherited_fields": {
|
||||
description:
|
||||
"Fields whose value comes from the template, for object fields the properties set on this instance",
|
||||
access: ["controller", "control"],
|
||||
readonly: ["controller"],
|
||||
type: "object",
|
||||
initialValue: {},
|
||||
hidden: true,
|
||||
},
|
||||
"factorio.version": {
|
||||
description:
|
||||
"Version of the game to run. Use 'latest' for the latest installed version, a release " +
|
||||
@@ -800,36 +929,31 @@ export function addPluginFieldDefinitions(
|
||||
|
||||
// The validator is dynamic based on the feature requirements of the plugin
|
||||
if (kind === "instanceConfigFields" && pluginInfo.features) {
|
||||
fieldDef.dependsOn = [];
|
||||
|
||||
const savePatching = pluginInfo.features.includes("SavePatching");
|
||||
if (savePatching) {
|
||||
fieldDef.dependsOn.push("factorio.enable_save_patching");
|
||||
const requirements: [string, string][] = [];
|
||||
if (pluginInfo.features.includes("SavePatching")) {
|
||||
requirements.push(["factorio.enable_save_patching", "save patching"]);
|
||||
}
|
||||
if (pluginInfo.features.includes("ScriptCommands")) {
|
||||
requirements.push(["factorio.enable_script_commands", "script commands"]);
|
||||
}
|
||||
if (pluginInfo.features.includes("LuaUdp")) {
|
||||
requirements.push(["factorio.enable_lua_udp", "Lua UDP"]);
|
||||
}
|
||||
|
||||
const scriptCommands = pluginInfo.features.includes("ScriptCommands");
|
||||
if (scriptCommands) {
|
||||
fieldDef.dependsOn.push("factorio.enable_script_commands");
|
||||
}
|
||||
|
||||
const luaUdp = pluginInfo.features.includes("LuaUdp");
|
||||
if (luaUdp) {
|
||||
fieldDef.dependsOn.push("factorio.enable_lua_udp");
|
||||
}
|
||||
|
||||
if (scriptCommands || savePatching || luaUdp) {
|
||||
if (requirements.length) {
|
||||
fieldDef.dependsOn = requirements.map(([field]) => field);
|
||||
// Default to not loaded when the instance does not meet the requirements
|
||||
fieldDef.initialValue = (config: classes.Config<any>) => requirements.every(
|
||||
([field]) => config.get(field)
|
||||
);
|
||||
fieldDef.validator = (enabled, config) => {
|
||||
if (!enabled) {
|
||||
return;
|
||||
}
|
||||
if (savePatching && !config.get("factorio.enable_save_patching")) {
|
||||
throw new Error(`Plugin ${pluginInfo.name} requires save patching`);
|
||||
}
|
||||
if (scriptCommands && !config.get("factorio.enable_script_commands")) {
|
||||
throw new Error(`Plugin ${pluginInfo.name} requires script commands`);
|
||||
}
|
||||
if (luaUdp && !config.get("factorio.enable_lua_udp")) {
|
||||
throw new Error(`Plugin ${pluginInfo.name} requires Lua UDP`);
|
||||
for (const [field, description] of requirements) {
|
||||
if (!config.get(field)) {
|
||||
throw new Error(`Plugin ${pluginInfo.name} requires ${description}`);
|
||||
}
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
import { Type, Static } from "@sinclair/typebox";
|
||||
|
||||
/**
|
||||
* A pending request from a host to join the cluster
|
||||
*
|
||||
* Requests are kept in memory on the controller only while the host
|
||||
* waits for them to be approved or rejected.
|
||||
*/
|
||||
export default class HostPairingDetails {
|
||||
constructor(
|
||||
/** Code shown by the host, used to identify the request. */
|
||||
public code: string,
|
||||
/** Name the host asked to have. */
|
||||
public name: string,
|
||||
/** Address the request was made from. */
|
||||
public remoteAddress: string,
|
||||
/** Version of the host that made the request. */
|
||||
public version = "",
|
||||
/** Millisecond Unix timestamp the request was made at. */
|
||||
public createdAtMs = 0,
|
||||
/** Millisecond Unix timestamp this entry was last updated at. */
|
||||
public updatedAtMs = 0,
|
||||
/** True if this request is no longer pending. */
|
||||
public isDeleted = false,
|
||||
) { }
|
||||
|
||||
get id() {
|
||||
return this.code;
|
||||
}
|
||||
|
||||
static jsonSchema = Type.Object({
|
||||
"code": Type.String(),
|
||||
"name": Type.String(),
|
||||
"remoteAddress": Type.String(),
|
||||
"version": Type.Optional(Type.String()),
|
||||
"createdAtMs": Type.Optional(Type.Number()),
|
||||
"updatedAtMs": Type.Optional(Type.Number()),
|
||||
"isDeleted": Type.Optional(Type.Boolean()),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
return new this(
|
||||
json.code,
|
||||
json.name,
|
||||
json.remoteAddress,
|
||||
json.version,
|
||||
json.createdAtMs,
|
||||
json.updatedAtMs,
|
||||
json.isDeleted,
|
||||
);
|
||||
}
|
||||
|
||||
toJSON() {
|
||||
const json: Static<typeof HostPairingDetails.jsonSchema> = {
|
||||
code: this.code,
|
||||
name: this.name,
|
||||
remoteAddress: this.remoteAddress,
|
||||
};
|
||||
if (this.version !== "") {
|
||||
json.version = this.version;
|
||||
}
|
||||
if (this.createdAtMs !== 0) {
|
||||
json.createdAtMs = this.createdAtMs;
|
||||
}
|
||||
if (this.updatedAtMs !== 0) {
|
||||
json.updatedAtMs = this.updatedAtMs;
|
||||
}
|
||||
if (this.isDeleted) {
|
||||
json.isDeleted = this.isDeleted;
|
||||
}
|
||||
return json;
|
||||
}
|
||||
}
|
||||
@@ -41,7 +41,11 @@ export default class InstanceDetails {
|
||||
public startedAtMs = 0,
|
||||
/** Millisecond Unix timestamp this entry was last updated at */
|
||||
public updatedAtMs = 0,
|
||||
public excludeFromStartAll = false
|
||||
public excludeFromStartAll = false,
|
||||
public isTemplate = false,
|
||||
public templateId?: number,
|
||||
/** Value of factorio.mod_pack_id, undefined means the controller default is used */
|
||||
public modPackId?: number,
|
||||
) {}
|
||||
|
||||
get isDeleted() {
|
||||
@@ -61,6 +65,9 @@ export default class InstanceDetails {
|
||||
"startedAtMs": Type.Optional(Type.Number()),
|
||||
"updatedAtMs": Type.Optional(Type.Number()),
|
||||
"excludeFromStartAll": Type.Optional(Type.Boolean()),
|
||||
"isTemplate": Type.Optional(Type.Boolean()),
|
||||
"templateId": Type.Optional(Type.Integer()),
|
||||
"modPackId": Type.Optional(Type.Integer()),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
@@ -73,7 +80,10 @@ export default class InstanceDetails {
|
||||
json.factorioVersion,
|
||||
json.startedAtMs,
|
||||
json.updatedAtMs,
|
||||
json.excludeFromStartAll
|
||||
json.excludeFromStartAll,
|
||||
json.isTemplate,
|
||||
json.templateId,
|
||||
json.modPackId,
|
||||
);
|
||||
}
|
||||
|
||||
@@ -102,6 +112,15 @@ export default class InstanceDetails {
|
||||
if (this.excludeFromStartAll !== false) {
|
||||
json.excludeFromStartAll = this.excludeFromStartAll;
|
||||
}
|
||||
if (this.isTemplate !== false) {
|
||||
json.isTemplate = this.isTemplate;
|
||||
}
|
||||
if (this.templateId !== undefined) {
|
||||
json.templateId = this.templateId;
|
||||
}
|
||||
if (this.modPackId !== undefined) {
|
||||
json.modPackId = this.modPackId;
|
||||
}
|
||||
|
||||
return json;
|
||||
}
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -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) {
|
||||
|
||||
@@ -15,6 +15,7 @@ export { default as Role } from "./Role.js";
|
||||
export { default as Note } from "./Note.js";
|
||||
export { default as InstanceDetails, InstanceStatus } from "./InstanceDetails.js";
|
||||
export { default as HostDetails } from "./HostDetails.js";
|
||||
export { default as HostPairingDetails } from "./HostPairingDetails.js";
|
||||
export { default as UserDetails } from "./UserDetails.js";
|
||||
export type { IUser } from "./UserDetails.js";
|
||||
export * from "./composites.js";
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
import { Type, Static } from "@sinclair/typebox";
|
||||
import { JsonString, StringEnum, StringKey, plainJson } from "./composites.js";
|
||||
import { JsonNumber, StringEnum, StringKey, jsonArray, plainJson } from "./composites.js";
|
||||
import { type LogEntry, levels } from "../logging.js";
|
||||
import { ControllerConfig, HostConfig } from "../config/index.js";
|
||||
import { ControllerConfig } from "../config/index.js";
|
||||
import { ExternalFactorioVersionSchema, LatestReleasesSchema } from "../external/index.js";
|
||||
import { PluginDetails } from "./messages_plugin.js";
|
||||
import HostPairingDetails from "./HostPairingDetails.js";
|
||||
|
||||
const LogEntrySchema = Type.Object({
|
||||
"level": StringKey(levels),
|
||||
@@ -120,52 +121,81 @@ export class ControllerConfigSetPropRequest {
|
||||
}
|
||||
}
|
||||
|
||||
export class HostGenerateTokenRequest {
|
||||
declare ["constructor"]: typeof HostGenerateTokenRequest;
|
||||
export class HostPairingListRequest {
|
||||
declare ["constructor"]: typeof HostPairingListRequest;
|
||||
static type = "request" as const;
|
||||
static src = "control" as const;
|
||||
static dst = "controller" as const;
|
||||
static permission = "core.host.generate_token" as const;
|
||||
|
||||
constructor(
|
||||
public hostId?: number,
|
||||
) { }
|
||||
|
||||
static jsonSchema = Type.Object({
|
||||
"hostId": Type.Optional(Type.Integer()),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
return new this(json.hostId);
|
||||
}
|
||||
|
||||
static Response = JsonString;
|
||||
static permission = "core.host.approve" as const;
|
||||
static Response = jsonArray(HostPairingDetails);
|
||||
}
|
||||
|
||||
export class HostConfigCreateRequest {
|
||||
declare ["constructor"]: typeof HostConfigCreateRequest;
|
||||
static type = "request" as const;
|
||||
static src = "control" as const;
|
||||
static dst = "controller" as const;
|
||||
static permission = "core.host.create_config" as const;
|
||||
export class HostPairingUpdatesEvent {
|
||||
declare ["constructor"]: typeof HostPairingUpdatesEvent;
|
||||
static type = "event" as const;
|
||||
static src = "controller" as const;
|
||||
static dst = "control" as const;
|
||||
static permission = "core.host.approve" as const;
|
||||
|
||||
constructor(
|
||||
public id: number | undefined,
|
||||
public name: string | undefined,
|
||||
public generateToken: boolean,
|
||||
public updates: HostPairingDetails[],
|
||||
) { }
|
||||
|
||||
static jsonSchema = Type.Object({
|
||||
"id": Type.Optional(Type.Integer()),
|
||||
"name": Type.Optional(Type.String()),
|
||||
"generateToken": Type.Boolean(),
|
||||
"updates": Type.Array(HostPairingDetails.jsonSchema),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
return new this(json.id, json.name, json.generateToken);
|
||||
return new this(json.updates.map(update => HostPairingDetails.fromJSON(update)));
|
||||
}
|
||||
}
|
||||
|
||||
export class HostPairingApproveRequest {
|
||||
declare ["constructor"]: typeof HostPairingApproveRequest;
|
||||
static type = "request" as const;
|
||||
static src = "control" as const;
|
||||
static dst = "controller" as const;
|
||||
static permission = "core.host.approve" as const;
|
||||
|
||||
constructor(
|
||||
/** Code of the pending request, case and dashes are ignored. */
|
||||
public code: string,
|
||||
/** Name to give the host instead of the one it asked for. */
|
||||
public name?: string,
|
||||
) { }
|
||||
|
||||
static jsonSchema = Type.Object({
|
||||
"code": Type.String(),
|
||||
"name": Type.Optional(Type.String()),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
return new this(json.code, json.name);
|
||||
}
|
||||
|
||||
static Response = plainJson(HostConfig.jsonSchema);
|
||||
/** Id of the host created. */
|
||||
static Response = JsonNumber;
|
||||
}
|
||||
|
||||
export class HostPairingRejectRequest {
|
||||
declare ["constructor"]: typeof HostPairingRejectRequest;
|
||||
static type = "request" as const;
|
||||
static src = "control" as const;
|
||||
static dst = "controller" as const;
|
||||
static permission = "core.host.approve" as const;
|
||||
|
||||
constructor(
|
||||
/** Code of the pending request, case and dashes are ignored. */
|
||||
public code: string,
|
||||
) { }
|
||||
|
||||
static jsonSchema = Type.Object({
|
||||
"code": Type.String(),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
return new this(json.code);
|
||||
}
|
||||
}
|
||||
|
||||
export class GetFactorioCredentialsRequest {
|
||||
|
||||
@@ -259,12 +259,12 @@ export class SyncUserListsEvent {
|
||||
}
|
||||
}
|
||||
|
||||
export class HostRevokeTokensRequest {
|
||||
declare["constructor"]: typeof HostRevokeTokensRequest;
|
||||
export class HostRevokeRequest {
|
||||
declare ["constructor"]: typeof HostRevokeRequest;
|
||||
static type = "request" as const;
|
||||
static src = "control" as const;
|
||||
static dst = "controller" as const;
|
||||
static permission = "core.host.revoke_token" as const;
|
||||
static permission = "core.host.revoke" as const;
|
||||
|
||||
constructor(
|
||||
public hostId: number,
|
||||
|
||||
@@ -176,6 +176,30 @@ export class InstanceConfigSetPropRequest {
|
||||
}
|
||||
}
|
||||
|
||||
export class InstanceConfigInheritFieldRequest {
|
||||
declare ["constructor"]: typeof InstanceConfigInheritFieldRequest;
|
||||
static type = "request" as const;
|
||||
static src = "control" as const;
|
||||
static dst = "controller" as const;
|
||||
static permission = "core.instance.update_config" as const;
|
||||
|
||||
constructor(
|
||||
public instanceId: number,
|
||||
public field: string,
|
||||
public prop?: string,
|
||||
) { }
|
||||
|
||||
static jsonSchema = Type.Object({
|
||||
"instanceId": Type.Integer(),
|
||||
"field": Type.String(),
|
||||
"prop": Type.Optional(Type.String()),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
return new this(json.instanceId, json.field, json.prop);
|
||||
}
|
||||
}
|
||||
|
||||
export class InstanceAssignRequest {
|
||||
declare ["constructor"]: typeof InstanceAssignRequest;
|
||||
static type = "request" as const;
|
||||
|
||||
@@ -4,57 +4,94 @@ import type { PluginNodeEnvInfo } from "../plugin.js";
|
||||
import { Address, MessageRequest } from "./messages_core.js";
|
||||
import type { IUser } from "./UserDetails.js";
|
||||
|
||||
export const pluginStateSchema = Type.Union([
|
||||
Type.Literal("loaded"),
|
||||
Type.Literal("disabled"),
|
||||
Type.Literal("unloadOnRestart"),
|
||||
Type.Literal("loadOnRestart"),
|
||||
Type.Literal("noEntrypoint"),
|
||||
Type.Literal("pendingInstall"),
|
||||
Type.Literal("removed"),
|
||||
Type.Literal("removedLoaded"),
|
||||
Type.Literal("nameTaken"),
|
||||
]);
|
||||
/**
|
||||
* State of a plugin on a machine
|
||||
*
|
||||
* - loaded: Running and loaded again on the next restart
|
||||
* - disabled: Not loaded as `<plugin>.load_plugin` is false
|
||||
* - unloadOnRestart: Running, but disabled since startup
|
||||
* - loadOnRestart: Not running, enabled since startup or skipped by recovery mode
|
||||
* - noEntrypoint: Has no entrypoint for this machine, so it is never loaded here
|
||||
* - pendingInstall: Installed since startup, loaded on the next restart
|
||||
* - removed: Uninstalled since startup while not running
|
||||
* - removedLoaded: Uninstalled since startup, running until the next restart
|
||||
* - nameTaken: Not loaded as another package provides a plugin with the same name
|
||||
*/
|
||||
export type PluginState = Static<typeof pluginStateSchema>;
|
||||
|
||||
/* This is similar to other plugin definitions but with lots removed */
|
||||
export class PluginDetails {
|
||||
constructor(
|
||||
public name: string,
|
||||
public title: string,
|
||||
public version: string,
|
||||
public loaded: boolean,
|
||||
public enabled: boolean,
|
||||
public state: PluginState,
|
||||
public description?: string,
|
||||
public npmPackage?: string,
|
||||
/** Version installed on disk, differs from version when an update is waiting for a restart */
|
||||
public installedVersion?: string,
|
||||
/** Installed after the machine started, will be loaded on the next restart */
|
||||
public pendingInstall?: boolean,
|
||||
/** Uninstalled after the machine started, will not be loaded on the next restart */
|
||||
public removed?: boolean,
|
||||
/** Name in the root package.json dependencies, differs from npmPackage for aliases */
|
||||
public dependencyName?: string,
|
||||
/** Has no entrypoint for this machine, so it is never loaded here */
|
||||
public noEntrypoint?: boolean,
|
||||
/** Not loaded as another package provides a plugin with the same name */
|
||||
public nameTaken?: boolean,
|
||||
) {}
|
||||
|
||||
static jsonSchema = Type.Object({
|
||||
name: Type.String(),
|
||||
title: Type.String(),
|
||||
version: Type.String(),
|
||||
// Missing from 2.0.3 and older, which require loaded and enabled instead
|
||||
state: Type.Optional(pluginStateSchema),
|
||||
loaded: Type.Boolean(),
|
||||
enabled: Type.Boolean(),
|
||||
description: Type.Optional(Type.String()),
|
||||
npmPackage: Type.Optional(Type.String()),
|
||||
installedVersion: Type.Optional(Type.String()),
|
||||
pendingInstall: Type.Optional(Type.Boolean()),
|
||||
removed: Type.Optional(Type.Boolean()),
|
||||
dependencyName: Type.Optional(Type.String()),
|
||||
noEntrypoint: Type.Optional(Type.Boolean()),
|
||||
nameTaken: Type.Optional(Type.Boolean()),
|
||||
});
|
||||
|
||||
static fromJSON(json: Static<typeof this.jsonSchema>) {
|
||||
return new this(
|
||||
json.name, json.title, json.version, json.loaded, json.enabled,
|
||||
json.description, json.npmPackage, json.installedVersion, json.pendingInstall, json.removed,
|
||||
json.dependencyName, json.noEntrypoint, json.nameTaken,
|
||||
json.name, json.title, json.version, json.state ?? this.loadState(json.loaded, json.enabled),
|
||||
json.description, json.npmPackage, json.installedVersion, json.dependencyName,
|
||||
);
|
||||
}
|
||||
|
||||
static fromNodeEnvInfo(pluginInfo: PluginNodeEnvInfo, loaded: boolean, enabled: boolean) {
|
||||
toJSON(): Static<typeof PluginDetails.jsonSchema> {
|
||||
return {
|
||||
name: this.name,
|
||||
title: this.title,
|
||||
version: this.version,
|
||||
state: this.state,
|
||||
loaded: this.loaded,
|
||||
enabled: this.loadsOnRestart,
|
||||
description: this.description,
|
||||
npmPackage: this.npmPackage,
|
||||
installedVersion: this.installedVersion,
|
||||
dependencyName: this.dependencyName,
|
||||
};
|
||||
}
|
||||
|
||||
/** State of a plugin known since startup */
|
||||
static loadState(loaded: boolean, enabled: boolean): PluginState {
|
||||
if (loaded) {
|
||||
return enabled ? "loaded" : "unloadOnRestart";
|
||||
}
|
||||
return enabled ? "loadOnRestart" : "disabled";
|
||||
}
|
||||
|
||||
static fromNodeEnvInfo(pluginInfo: PluginNodeEnvInfo, state: PluginState) {
|
||||
return new this(
|
||||
pluginInfo.name, pluginInfo.title, pluginInfo.version, loaded, enabled,
|
||||
pluginInfo.name, pluginInfo.title, pluginInfo.version, state,
|
||||
pluginInfo.description, pluginInfo.npmPackage,
|
||||
);
|
||||
}
|
||||
@@ -63,10 +100,25 @@ export class PluginDetails {
|
||||
static fromPackageJson(packageName: string, packageJson: any, npmPackage?: string, dependencyName?: string) {
|
||||
const description = typeof packageJson.description === "string" ? packageJson.description : undefined;
|
||||
return new this(
|
||||
packageName, packageName, packageJson.version, false, false,
|
||||
description, npmPackage, packageJson.version, true, undefined, dependencyName,
|
||||
packageName, packageName, packageJson.version, "pendingInstall",
|
||||
description, npmPackage, packageJson.version, dependencyName,
|
||||
);
|
||||
}
|
||||
|
||||
/** Running on the machine now */
|
||||
get loaded() {
|
||||
return ["loaded", "unloadOnRestart", "removedLoaded"].includes(this.state);
|
||||
}
|
||||
|
||||
/** Running on the machine after the next restart */
|
||||
get loadsOnRestart() {
|
||||
return ["loaded", "loadOnRestart", "pendingInstall"].includes(this.state);
|
||||
}
|
||||
|
||||
/** Uninstalled since startup */
|
||||
get removed() {
|
||||
return this.state === "removed" || this.state === "removedLoaded";
|
||||
}
|
||||
}
|
||||
|
||||
export class PluginListRequest {
|
||||
|
||||
@@ -79,7 +79,7 @@ export async function loadJsonAsMap(filePath: string): Promise<Map<string, unkno
|
||||
*/
|
||||
export async function saveMapAsJson(filePath: string, map: Map<string, unknown>) {
|
||||
let obj = mapToObject(map);
|
||||
await libFileOps.safeOutputFile(filePath, JSON.stringify(obj, null, "\t"));
|
||||
await libFileOps.atomicOverwriteFile(filePath, JSON.stringify(obj, null, "\t"));
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -139,7 +139,7 @@ export async function loadJsonArrayAsMap(filePath: string): Promise<Map<unknown,
|
||||
* @throws {Error} if an error occured writing to the file.
|
||||
*/
|
||||
export async function saveMapAsJsonArray(filePath: string, map: Map<unknown, { id: unknown }>) {
|
||||
await libFileOps.safeOutputFile(filePath, JSON.stringify([...map.values()], null, "\t"));
|
||||
await libFileOps.atomicOverwriteFile(filePath, JSON.stringify([...map.values()], null, "\t"));
|
||||
}
|
||||
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@ import path from "path";
|
||||
import fs from "node:fs/promises";
|
||||
import { EventEmitter } from "events";
|
||||
|
||||
import { safeOutputFile } from "./file_ops.js";
|
||||
import { atomicOverwriteFile } from "./file_ops.js";
|
||||
import { SubscribableValue } from "./subscriptions.js";
|
||||
import { logger } from "./logging.js";
|
||||
import { ControllerConfig } from "./config/index.js";
|
||||
@@ -56,7 +56,7 @@ export class JsonDatastoreProvider<
|
||||
// Save the data to the json file
|
||||
async save(data: Map<string, V>) {
|
||||
logger.verbose(`Saving ${this.filePath}`);
|
||||
await safeOutputFile(this.filePath, JSON.stringify(Object.fromEntries(data), null, "\t"));
|
||||
await atomicOverwriteFile(this.filePath, JSON.stringify(Object.fromEntries(data), null, "\t"));
|
||||
}
|
||||
|
||||
// Load the data from the json file
|
||||
@@ -91,7 +91,7 @@ export class JsonDatastoreProvider<
|
||||
logger.warn(
|
||||
`Duplicates detected in ${this.filePath}, a backup was written to: ${backupPath}`
|
||||
);
|
||||
await safeOutputFile(backupPath, JSON.stringify(rawJson, null, "\t"));
|
||||
await atomicOverwriteFile(backupPath, JSON.stringify(rawJson, null, "\t"));
|
||||
}
|
||||
|
||||
return result;
|
||||
@@ -115,7 +115,7 @@ export class JsonIdDatastoreProvider<
|
||||
// Save the data to the json file
|
||||
async save(data: Map<V["id"], V>) {
|
||||
logger.verbose(`Saving ${this.filePath}`);
|
||||
await safeOutputFile(this.filePath, JSON.stringify([...data.values()], null, "\t"));
|
||||
await atomicOverwriteFile(this.filePath, JSON.stringify([...data.values()], null, "\t"));
|
||||
}
|
||||
|
||||
// Load the data from the json file
|
||||
@@ -150,7 +150,7 @@ export class JsonIdDatastoreProvider<
|
||||
logger.warn(
|
||||
`Duplicates detected in ${this.filePath}, a backup was written to: ${backupPath}`
|
||||
);
|
||||
await safeOutputFile(backupPath, JSON.stringify(rawJson, null, "\t"));
|
||||
await atomicOverwriteFile(backupPath, JSON.stringify(rawJson, null, "\t"));
|
||||
}
|
||||
|
||||
return result;
|
||||
@@ -166,6 +166,7 @@ export abstract class Datastore<
|
||||
"update": [ updates: U[] ],
|
||||
}> {
|
||||
private dirty = false;
|
||||
private saving: Promise<void> = Promise.resolve();
|
||||
|
||||
constructor(
|
||||
private provider: DatastoreProvider<K, V> = new MemoryDatastoreProvider(),
|
||||
@@ -181,10 +182,22 @@ export abstract class Datastore<
|
||||
|
||||
// Save the datastore to the provider
|
||||
async save() {
|
||||
if (this.dirty) {
|
||||
await this.provider.save(this.data);
|
||||
// Saves run one at a time so an older snapshot can't be written after a newer one.
|
||||
const save = this.saving.catch(() => {}).then(async () => {
|
||||
if (!this.dirty) {
|
||||
return;
|
||||
}
|
||||
// Cleared before writing so changes made while saving are saved by the next save.
|
||||
this.dirty = false;
|
||||
}
|
||||
try {
|
||||
await this.provider.save(this.data);
|
||||
} catch (err) {
|
||||
this.dirty = true;
|
||||
throw err;
|
||||
}
|
||||
});
|
||||
this.saving = save;
|
||||
await save;
|
||||
}
|
||||
|
||||
// Load the datastore from the provider
|
||||
|
||||
+52
-2
@@ -1,5 +1,5 @@
|
||||
import { Static, Type } from "@sinclair/typebox";
|
||||
import { FullVersionSchema, integerFullVersion, isFullVersion } from "../data/version.js";
|
||||
import { FullVersion, FullVersionSchema, integerFullVersion, isFullVersion } from "../data/version.js";
|
||||
|
||||
const ARCHIVE_URL = "https://factorio.com/download/archive/";
|
||||
|
||||
@@ -9,11 +9,61 @@ const ARCHIVE_URL = "https://factorio.com/download/archive/";
|
||||
export const ExternalFactorioVersionSchema = Type.Object({
|
||||
stable: Type.Boolean(),
|
||||
version: FullVersionSchema,
|
||||
/** @deprecated Linux x64 only, use {@link factorioHeadlessUrl} instead. */
|
||||
headlessUrl: Type.String(),
|
||||
});
|
||||
|
||||
export type ExternalFactorioVersion = Static<typeof ExternalFactorioVersionSchema>;
|
||||
|
||||
/** Platforms Factorio may publish headless builds for, named as in Node's process.platform */
|
||||
export type FactorioHeadlessPlatform = "linux" | "win32";
|
||||
|
||||
/** CPU architectures Factorio may publish headless builds for, named as in Node's process.arch */
|
||||
export type FactorioHeadlessArch = "x64" | "arm64";
|
||||
|
||||
/** First Factorio version with an ARM64 Linux headless build */
|
||||
export const minimumArm64HeadlessVersion = "2.1.18";
|
||||
|
||||
/**
|
||||
* Check if Factorio publishes a headless build of a version
|
||||
*
|
||||
* @param version - Factorio version to check.
|
||||
* @param platform - Platform of the build.
|
||||
* @param arch - CPU architecture of the build.
|
||||
* @returns true if the build can be downloaded.
|
||||
*/
|
||||
export function hasFactorioHeadless(
|
||||
version: FullVersion,
|
||||
platform: FactorioHeadlessPlatform,
|
||||
arch: FactorioHeadlessArch,
|
||||
) {
|
||||
if (platform !== "linux") {
|
||||
return false;
|
||||
}
|
||||
return arch === "x64" || integerFullVersion(version) >= integerFullVersion(minimumArm64HeadlessVersion);
|
||||
}
|
||||
|
||||
/**
|
||||
* Download URL of the headless build of a Factorio version
|
||||
*
|
||||
* @param version - Factorio version to download.
|
||||
* @param platform - Platform of the build.
|
||||
* @param arch - CPU architecture of the build.
|
||||
* @returns URL redirecting to the archive.
|
||||
* @throws Error if Factorio has no headless build for the platform and arch.
|
||||
*/
|
||||
export function factorioHeadlessUrl(
|
||||
version: FullVersion,
|
||||
platform: FactorioHeadlessPlatform,
|
||||
arch: FactorioHeadlessArch,
|
||||
) {
|
||||
if (!hasFactorioHeadless(version, platform, arch)) {
|
||||
throw new Error(`Factorio ${version} has no headless build for ${platform} ${arch}`);
|
||||
}
|
||||
const build = arch === "arm64" ? "linux-arm64" : "linux64";
|
||||
return `https://www.factorio.com/get-download/${version}/headless/${build}`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fetch all factorio versions that support headless
|
||||
*
|
||||
@@ -60,7 +110,7 @@ function parseFactorioVersions(html: string): ExternalFactorioVersion[] {
|
||||
versions.set(version, {
|
||||
version: version,
|
||||
stable: kind === "stable",
|
||||
headlessUrl: `https://www.factorio.com/get-download/${version}/headless/linux64`,
|
||||
headlessUrl: factorioHeadlessUrl(version, "linux", "x64"),
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import zlib from "zlib";
|
||||
import * as zlib from "#zlib_sync";
|
||||
|
||||
class MapReaderState {
|
||||
pos = 0;
|
||||
|
||||
@@ -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";
|
||||
@@ -89,7 +88,7 @@ export async function getTempFile(prefix = "tmp.", suffix = "", tmpdir = "./") {
|
||||
}
|
||||
|
||||
/**
|
||||
* Safely overwrite file data
|
||||
* Atomically overwrite file data
|
||||
*
|
||||
* Writes the passed data to a temporary file and rename it over the target
|
||||
* file. If the operation fails because the parent directory does not exist, it
|
||||
@@ -105,7 +104,7 @@ export async function getTempFile(prefix = "tmp.", suffix = "", tmpdir = "./") {
|
||||
* @param data - Content to write.
|
||||
* @param options - see fs.writeFile, `flag` and `flush` may not be used.
|
||||
*/
|
||||
export async function safeOutputFile(
|
||||
export async function atomicOverwriteFile(
|
||||
file: string,
|
||||
data: string | Buffer,
|
||||
options?: Omit<
|
||||
@@ -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);
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
Loaded 100 of 277 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user