mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-13 23:14:53 +09:00
Danielv123
49a0b27d29
Revoking a host now unassigns its instances instead of being refused while it has any, and removes its system metrics. Approving and revoking no longer force a save. Hosts are saved by autosave and on exit like everything else, which also removes the approving state from pairing requests. The approval code and link are logged as warnings so they show up in the systemd service, which only prints warnings and above. The pairing limits are now the controller.host_pairing_timeout and controller.host_pairing_max_pending config values, 0 removes the limit. Subscribers take an optional permitted function, used for the pairing requests instead of overrides in a subclass.
82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
# Migrating Plugins to 2.1
|
|
|
|
This guide covers the changes needed to bring a plugin written for 2.0 up to 2.1.
|
|
Plugins still on an alpha should start with the [2.0 guide](plugin-migration-to-2.0.md).
|
|
|
|
|
|
## 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).
|
|
Replace `RequestError` with the class that fits:
|
|
|
|
- Invalid input: `ValidationError`.
|
|
- Operation disabled by config: `ForbiddenError`.
|
|
- Missing instance, user, save etc.: `NotFoundError`.
|
|
- Instance running, name taken etc.: `ConflictError`.
|
|
- Host not connected, instance not running: `UnavailableError`.
|
|
- Timeouts: `TimeoutError`.
|
|
|
|
`catch` blocks that check `err instanceof RequestError` should check `ClientError` instead, or the specific class.
|
|
Checks of `err.code` for remote errors can use `instanceof`, e.g. `err instanceof lib.SessionLost`.
|
|
|
|
The config errors `lib.InvalidValue`, `lib.InvalidField` and `lib.InvalidAccess` were renamed to `lib.InvalidValueError`, `lib.InvalidFieldError` and `lib.InvalidAccessError`.
|
|
|
|
Errors of classes that are not registered, like a `TypeError` from a bug, are received as `InternalServerError`.
|
|
Plugins that define their own error classes need to list them in `errors` of the plugin declaration.
|
|
|
|
|
|
## Build the web module with Vite
|
|
|
|
The web interface is now built with Vite instead of webpack, and plugin web modules are loaded as ES modules instead of through Module Federation.
|
|
A plugin built with webpack fails to load with the error "Incompatible dist/web/manifest.json, the plugin must be rebuilt with Vite".
|
|
|
|
Delete `webpack.config.cjs` and add a `vite.config.js` next to `package.json`:
|
|
|
|
```js
|
|
import { defineConfig } from "vite";
|
|
import { clusterioPlugin } from "@clusterio/web_ui/vite.mjs";
|
|
|
|
export default defineConfig({
|
|
plugins: [clusterioPlugin()],
|
|
});
|
|
```
|
|
|
|
In `package.json` replace `webpack-cli --mode production` in the `prepare` script with `vite build`, and replace the `webpack`, `webpack-cli` and `webpack-merge` dev dependencies with `vite`.
|
|
Add `vite.config.js` to `.npmignore` if you had `webpack.config.js` there.
|
|
|
|
`clusterioPlugin` exposes `index.ts` (or `index.js`) as `"./"`, `package.json` as `"./package.json"` and `web/index.tsx` (or `.ts`, `.jsx`, `.js`) as `"./web"`.
|
|
These are the same keys the plugin template used with webpack, so `webEntrypoint: "./web"` stays as it is.
|
|
If your webpack config exposed other paths, move the code so it is reachable from `web/index.tsx`.
|
|
|
|
The web interface provides `@clusterio/lib`, `@clusterio/web_ui`, `@sinclair/typebox`, `antd`, `react`, `react-dom`, `react-router` and `react-router-dom` to plugins.
|
|
These are left as imports in the plugin bundle and resolved by the browser, there is no need to list them as shared.
|
|
Everything else is bundled into the plugin, including `@ant-design/icons`.
|
|
Import `react-dom/client` and `react/jsx-runtime` by those names, other subpaths of the shared packages are bundled as a separate copy.
|
|
|
|
Imports of `assert`, `buffer`, `events`, `os`, `path`, `process`, `stream`, `util` and `zlib` resolve to the same browser packages as before, provided by `@clusterio/web_ui`.
|
|
|
|
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`.
|
|
|
|
|
|
## 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` 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.
|