mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-18 23:33:12 +09:00
Correct developer guidance and skip heavy CI for documentation changes (#1090)
Add a minimal AGENTS.md, update documentation and optimize the CI runs to not run actions for which there are no changes present
This commit is contained in:
1 parent
d5d4eb7fef
commit
c4f48b6c12
17 files changed
+968
-244
No files matched your search
+142
-83
@@ -41,6 +41,9 @@ The usual guides for creating such packages apply.
|
||||
At minimum the `package.json` file must contain a version entry.
|
||||
For automatic discovery, include `"clusterio-plugin"` in the package's `"keywords"` array.
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -74,15 +77,15 @@ For example, a plugin that needs an export map can use:
|
||||
Here's an example of `index.js`:
|
||||
|
||||
```js
|
||||
import * as messages from "./messages.js";
|
||||
|
||||
export const plugin = {
|
||||
name: "foo_frobber",
|
||||
title: "Foo Frobber",
|
||||
description: "Does advanced frobnication",
|
||||
instanceEntrypoint: "instance.js",
|
||||
controllerEntrypoint: "controller.js",
|
||||
messages: {
|
||||
/* See below */
|
||||
},
|
||||
messages: [messages.Frobnicate],
|
||||
};
|
||||
```
|
||||
|
||||
@@ -120,11 +123,24 @@ The following properties are recognized:
|
||||
Object mapping controller configuration fields to `FieldDefinition` objects for this plugin.
|
||||
See [Plugin Configuration](#plugin-configuration)
|
||||
|
||||
**hostEntrypoint**:
|
||||
Optional path to the Node.js module exporting the host entrypoint function.
|
||||
|
||||
**hostConfigFields**:
|
||||
Object mapping host configuration fields to `FieldDefinition` objects.
|
||||
|
||||
**ctlEntrypoint**:
|
||||
Path to a Node.js module relative to the plugin directory which exports the clusterioctl entrypoint function for this plugin.
|
||||
This is an optional paramater.
|
||||
A plugin can be made that only runs on the clusterioctl side.
|
||||
|
||||
**ctlConfigFields**:
|
||||
Object mapping ctl configuration fields to `FieldDefinition` objects.
|
||||
|
||||
**webEntrypoint**:
|
||||
Optional Module Federation exposure key for the web entrypoint, such as `"./web"`.
|
||||
It must match the key in the plugin's webpack `exposes` configuration; it is not a Node.js file path.
|
||||
|
||||
**migrationEntrypoint**:
|
||||
Path to a Node.js module relative to the plugin directory which exports the migration entrypoint function for this plugin.
|
||||
This is an optional parameter.
|
||||
@@ -135,7 +151,7 @@ The following properties are recognized:
|
||||
See [Handling Invalid Configuration](#handling-invalid-configuration)
|
||||
|
||||
**messages**:
|
||||
Object with link messages definitions for this plugin.
|
||||
Array of request and event classes for this plugin.
|
||||
See guide for [defining link messages](#defining-link-messages) below.
|
||||
|
||||
**permissions**:
|
||||
@@ -149,7 +165,8 @@ The only restriction imposed on modules embedded into plugins is that they must
|
||||
While there is no standard for how to organize a plugin it's recommended to put the controller entrypoint into controller.js and the instance entrypoint into instance.js.
|
||||
You can put them into whatever file you want (even the same one for both).
|
||||
|
||||
The entrypoint paths must include the .js extension and use forward slashes for directory separators if any.
|
||||
Node.js entrypoint paths must include the `.js` extension and use forward slashes for directory separators.
|
||||
This rule does not apply to the `webEntrypoint` exposure key.
|
||||
|
||||
|
||||
## Defining the plugin entrypoint
|
||||
@@ -236,7 +253,7 @@ try {
|
||||
// Operation that should not throw but may end up throwing
|
||||
} catch (err) {
|
||||
logger.error(`Operation failed:\n${err.stack}`);
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
For plugin hooks expections thrown are automatically catched and logged, but for event handlers registered on EventEmitters it's critical that exceptions are catched and handled appropriately.
|
||||
@@ -245,7 +262,7 @@ For plugin hooks expections thrown are automatically catched and logged, but for
|
||||
## Plugin Configuration
|
||||
|
||||
Clusterio provides a configuration system that handles storing, distributing, editing and validating config fields for you.
|
||||
You can take advantage of it by declaring config fields under either `controllerConfigFields` or `instanceConfigFields` in the `plugin` export.
|
||||
Declare fields under `controllerConfigFields`, `hostConfigFields`, `instanceConfigFields`, or `ctlConfigFields` in the `plugin` export.
|
||||
For example in index.js:
|
||||
|
||||
```ts
|
||||
@@ -340,6 +357,8 @@ In JavaScript the `declare module` block is not needed.
|
||||
|
||||
Permissions declared this way are registered when the plugin is loaded.
|
||||
The older `lib.definePermission()` function still works, but a plugin should not use both for the same permission name.
|
||||
Controller-side permission checks are authoritative; hiding a web UI control does not authorize or protect its underlying request.
|
||||
Declare the [permission on control-origin messages](#static-permission) and test denied requests as well as allowed ones.
|
||||
|
||||
|
||||
## Migrating Stored Data
|
||||
@@ -367,7 +386,7 @@ They run synchronously, a handler that throws stops the controller or host from
|
||||
`lib.renameConfigField`, `lib.renameConfigPrefix`, `lib.renamePermission` and `lib.renamePermissionPrefix` cover the common case of renaming.
|
||||
|
||||
Handlers run every time the data is loaded and must leave data that is already migrated unchanged.
|
||||
For changes that can't be repeated, each config has a hidden `<plugin>.version` field with the version of the plugin it was last loaded with, which is updated after the migrations have run:
|
||||
For changes that can't be repeated, controller, host, and instance configs have a hidden `<plugin>.version` field with the version of the plugin they were last loaded with, which is updated after the migrations have run:
|
||||
|
||||
```js
|
||||
hooks.instanceConfig.attach(plugin.name, config => {
|
||||
@@ -474,7 +493,7 @@ async function handleFoo(content) {
|
||||
**Note:** This only handles IPC events, all other events must use `on`. You should not include the `ipc-` prefix when using this method. Error logging is handled for you, if you want custom error handling use `on`.
|
||||
|
||||
It's recommended to either use the plugin name as the channel name or to prefix the channel name with the name of the plugin if you need multiple channels.
|
||||
It's also important to catch any errors that might occur as they will otherwise be propogated to the instance code and kill the server.
|
||||
With raw `server.on(...)` listeners, catch errors in the handler; `server.handle(...)` already handles error logging for IPC handlers.
|
||||
|
||||
Data out from Factorio does not have the same limits as data into Factorio, RCON responses can be in 100kB range without causing issues, and payloads to the `send_json` API can be in the 4MB range provided the server has a fast enough storage system.
|
||||
|
||||
@@ -496,59 +515,59 @@ Events are simple one-way notifications that invoke a handler on the target it's
|
||||
Requests are pairs of request and response messages where the request is sent to the target and the response is the reply back from the target.
|
||||
The requests are similar to HTTP requests, except both parties of a link may initiate one.
|
||||
|
||||
Messages are defined as items of the `plugin.messages` array exported by `index.js`.
|
||||
For example, the following could be defined in `plugin`:
|
||||
Export message classes from `messages.js` and list them in the `plugin.messages` array in `index.js`, as in the [plugin structure example](#plugin-structure).
|
||||
For example, `messages.js` can contain:
|
||||
|
||||
```js
|
||||
messages: [
|
||||
class Frobnicate {
|
||||
static plugin = "foo_frobber"; // Plugin name
|
||||
static type = "request";
|
||||
static src = "controller";
|
||||
static dst = "instance";
|
||||
static jsonSchema = {
|
||||
export class Frobnicate {
|
||||
static plugin = "foo_frobber";
|
||||
static type = "request";
|
||||
static src = "instance";
|
||||
static dst = "controller";
|
||||
static jsonSchema = {
|
||||
type: "object",
|
||||
properties: {
|
||||
verbosity: { type: "integer" },
|
||||
special: { type: "boolean" },
|
||||
},
|
||||
required: ["verbosity"],
|
||||
additionalProperties: false,
|
||||
};
|
||||
constructor(json) {
|
||||
this.verbosity = json.verbosity;
|
||||
this.special = json.special;
|
||||
}
|
||||
static fromJSON(json) {
|
||||
return new Frobnicate(json);
|
||||
}
|
||||
toJSON() {
|
||||
return {
|
||||
verbosity: this.verbosity,
|
||||
special: this.special,
|
||||
};
|
||||
}
|
||||
static Response = {
|
||||
jsonSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
"verbosity": { type: "integer" },
|
||||
"special": { type: "boolean" },
|
||||
},
|
||||
required: ["verbosity"],
|
||||
additionalProperties: false,
|
||||
};
|
||||
constructor(json) {
|
||||
this.verbosity = json.verbosity;
|
||||
this.special = json.special;
|
||||
}
|
||||
static fromJSON(json) {
|
||||
return new Frobnicate(json);
|
||||
}
|
||||
toJSON() {
|
||||
return {
|
||||
verbosity: this.verbosity,
|
||||
special: this.special,
|
||||
};
|
||||
}
|
||||
static Response = {
|
||||
jsonSchema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
"report": {
|
||||
type: "array",
|
||||
items: { type: "string" },
|
||||
},
|
||||
report: {
|
||||
type: "array",
|
||||
items: { type: "string" },
|
||||
},
|
||||
},
|
||||
fromJSON(json) {
|
||||
return json
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
required: ["report"],
|
||||
additionalProperties: false,
|
||||
},
|
||||
fromJSON(json) {
|
||||
return json;
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
This specifies a request that can be sent from the controller to an instance, being routed through the correct host behind the scenes.
|
||||
This specifies a request sent from an instance to the controller through its host.
|
||||
The request data must contain the property `verbosity` with an integer number as the value, and it may also contain a boolean `special` property.
|
||||
It also defines that the response sent may contain a `report` property mapping to an array of strings.
|
||||
The response must contain a `report` property containing an array of strings.
|
||||
|
||||
The following properties are recognized as part of a message class:
|
||||
|
||||
@@ -577,6 +596,34 @@ If the target is multiple hops away it the message will be forwarded towards its
|
||||
For example a message sent from a control connection an instance will be forwarded by the controller to the relevant host and from the host to the correct instance.
|
||||
Messages sent to a different destination will be rejected.
|
||||
|
||||
#### static permission
|
||||
|
||||
Required for request and event classes whose `src` includes `"control"`.
|
||||
Use a permission name, a synchronous permission-checking function, or `null` when every authenticated control client is deliberately allowed to send the message.
|
||||
Registration rejects control-origin messages with no permission declaration.
|
||||
|
||||
A callback receives `(user, message)`, where `message` is the raw wire envelope.
|
||||
It runs on the controller before destination payload validation and deserialization, so `message.data` is untrusted and may be missing or malformed.
|
||||
Check any required payload shape before inspecting fields, and use `user.checkPermission(...)` or throw `PermissionError` for a normal denial.
|
||||
For example, this checks the payload shape needed to choose a permission; the destination schema still validates the full payload:
|
||||
|
||||
```js
|
||||
import { PermissionError } from "@clusterio/lib";
|
||||
|
||||
function checkFrobnicatePermission(user, message) {
|
||||
const data = message.data;
|
||||
if (!data || typeof data !== "object" || typeof data.special !== "boolean") {
|
||||
throw new PermissionError("Expected a boolean special field");
|
||||
}
|
||||
user.checkPermission(data.special ? "foo_frobber.special" : "foo_frobber.frobnicate");
|
||||
}
|
||||
```
|
||||
|
||||
To use this callback, declare both permissions, require `special` in the message schema, and set `static permission = checkFrobnicatePermission` on a class that accepts `"control"` sources.
|
||||
The `Frobnicate` example above only accepts instances and therefore does not need a permission declaration.
|
||||
Do not make permission callbacks async: their result is not awaited, and returning `false` does not deny access.
|
||||
Unexpected exceptions are contained and logged as errors; they are not a substitute for intentional permission denials.
|
||||
|
||||
#### static jsonSchema
|
||||
|
||||
A JSON schema that specifies what's valid to send in the message.
|
||||
@@ -588,7 +635,8 @@ This should return an object that's valid according to `jsonSchema` and accepted
|
||||
|
||||
#### static fromJSON
|
||||
|
||||
Required function to restore the class from a JSON object.
|
||||
Function to restore the class from a JSON object; it must be provided together with `jsonSchema` for messages carrying data.
|
||||
Messages without data can omit both and are constructed without arguments.
|
||||
This function is called when the message reaches its destination and is expected to return an identical instance of the class.
|
||||
I.e. the result of `fromJSON(JSON.parse(JSON.stringify(instance)))` should be a complete copy of the message.
|
||||
|
||||
@@ -597,54 +645,62 @@ I.e. the result of `fromJSON(JSON.parse(JSON.stringify(instance)))` should be a
|
||||
Optional [JSON sterilisable class](/docs/devs/json-serialisable-classes.md) that specifies the response to the request.
|
||||
Required properties are `jsonSchema` and `fromJSON`.
|
||||
|
||||
Test JSON round trips, invalid payloads, allowed source/destination types, and authorization failures when changing messages.
|
||||
Keep registration, schemas, serialization, permissions, and handlers consistent.
|
||||
|
||||
|
||||
## Sending Link Messages
|
||||
|
||||
Link messages are sent by calling the `.sendTo()` method on a connection object with the destination and the data you want to send, where the data is an instance of one of the defined message classes in plugin.messages.
|
||||
For example:
|
||||
|
||||
```js
|
||||
import * as messages from "./messages.js";
|
||||
|
||||
// In an instance entrypoint
|
||||
async function frobnicate(instance) {
|
||||
const response = await instance.sendTo("controller", new messages.Frobnicate({
|
||||
const response = await instance.sendTo("controller", new messages.Frobnicate({
|
||||
verbosity: 2,
|
||||
special: false,
|
||||
}));
|
||||
console.log(response); // { report: [...] }
|
||||
}
|
||||
```
|
||||
Because the send and handle methods rely on this, you should always call them directly on the connection object.
|
||||
|
||||
If you extract them into a variable, destructure them, or pass them as unbound callbacks, they lose their this context. The method will eventually crash with an error like Cannot read properties of undefined (reading 'sendRequest').
|
||||
|
||||
While it's fine to type cast a direct method invocation, casting and then storing the result causes that same dangerous loss of context.
|
||||
|
||||
Here is what that looks like in practice:
|
||||
Register the corresponding handler on the controller:
|
||||
|
||||
```js
|
||||
// ❌ BAD: The extracted method loses its `this` binding and crashes when called.
|
||||
const send = instance.sendTo;
|
||||
send("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
import * as messages from "./messages.js";
|
||||
|
||||
// ✅ GOOD: Call it directly on the connection object. (Cast args/results here if needed).
|
||||
instance.sendTo("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
|
||||
// ✅ GOOD: Explicitly bind the receiver if you need to pass a method as a value (like a handler).
|
||||
instance.handle(messages.Frobnicate, plugin.handleFrobnicate.bind(plugin));
|
||||
export default async function({ controller }) {
|
||||
controller.handle(messages.Frobnicate, async request => ({
|
||||
report: [`Frobnication verbosity: ${request.verbosity}`],
|
||||
}));
|
||||
}
|
||||
```
|
||||
|
||||
The send and handle methods depend on `this`.
|
||||
Call them on their connection object, or explicitly bind them when passing a method as a value:
|
||||
|
||||
```js
|
||||
const send = instance.sendTo.bind(instance);
|
||||
const response = await send("controller", new messages.Frobnicate({ verbosity: 2, special: false }));
|
||||
```
|
||||
|
||||
Extracting an unbound method loses its receiver; storing a returned response does not.
|
||||
For classes with `static type = "request"` the send method is async and returns a promise that resolves to the response data received from the target it was sent to, or rejects with an error if the request failed.
|
||||
The destination specification can either be the ID of a particular control, host or instance, or one of the keywords used to send to multiple targets at once.
|
||||
The destination can identify a particular control, host, or instance.
|
||||
The `allHosts`, `allControls`, and `allInstances` broadcast destinations are for events, not requests.
|
||||
|
||||
Example destinations:
|
||||
|
||||
```js
|
||||
sendTo("controller", message);
|
||||
sendTo("allHosts", message);
|
||||
sendTo("allControls", message);
|
||||
sendTo("allInstances", message);
|
||||
sendTo({ hostId: 123 }, message);
|
||||
sendTo({ instanceId: 123 }, message);
|
||||
sendTo({ controlId: 123 }, message);
|
||||
connection.sendTo("controller", message);
|
||||
connection.sendTo("allHosts", event);
|
||||
connection.sendTo("allControls", event);
|
||||
connection.sendTo("allInstances", event);
|
||||
connection.sendTo({ hostId: 123 }, message);
|
||||
connection.sendTo({ instanceId: 123 }, message);
|
||||
connection.sendTo({ controlId: 123 }, message);
|
||||
```
|
||||
|
||||
### Handling connection events
|
||||
@@ -656,20 +712,23 @@ This is signaled to controller plugins via the `prepareHostDisconnect` hook and
|
||||
After the prepare disconnect the connection will be closed, which will result in pending requests and events being dropped.
|
||||
Plugins must respond to the prepare disconnect by stopping any processess it does that send events or requests over the link in question.
|
||||
This can be accomplished either through listening for the prepare disconnect hook, or by checking the `connected` property of the `HostConnection` class and `Host` class on the controller and host respectively.
|
||||
For example the sending of an event from an instance plugin can be stopped while the connection is not connected, not in the dropped state, and not in the process of discunnecting by using the following code:
|
||||
For example, an instance plugin can avoid starting a request while the host is disconnected or preparing to disconnect:
|
||||
|
||||
```js
|
||||
if (host.connected) {
|
||||
instance.sendTo("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
await instance.sendTo("controller", new messages.Frobnicate({ verbosity: 2, special: false }));
|
||||
}
|
||||
```
|
||||
|
||||
If the event or request needs to be sent to the controller it can be put into a queue and sent out when the connection is established again.
|
||||
The re-establishement of the connection is notified to plugins via the `connect` event to the `controllerConnectionEvent` and `hostConnectionEvent` hooks.
|
||||
The connection hooks report `connect` for a new session and `resume` for a retained session.
|
||||
Keep application queues separate from messages already accepted into the connector buffer; blindly sending both again can duplicate an operation.
|
||||
|
||||
The second connection event which is of lesser importance to respond to is the `drop` connection event served through `controllerConnectionEvent` for instance plugins and through `hostConnectionEvent` for controller plugins.
|
||||
This is raised when the connection between the controller and host in question is lost, most likely due to networking issues.
|
||||
When in the dropped state the host will keep trying to reconnect to the controller in order to re-establish it, and if successful no events or requests will be lost.
|
||||
When in the dropped state the host retries the connection and attempts to resume the retained session.
|
||||
Successful resumption replays unacknowledged buffered messages; expiry, invalidation, or buffer overflow can instead end the session.
|
||||
This is not an application-level exactly-once guarantee; stateful plugins need their own recovery and duplicate-handling strategy.
|
||||
However while in the dropped state any requests and events sent gets queued up in memory until the connection is either re-established or the session times out.
|
||||
This means that if your plugin sends a lot of events or requests, they can end up being queued up in a buffer and sent out all at once the connection is re-estabished.
|
||||
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.
|
||||
@@ -699,7 +758,7 @@ It's recommended that plugin metrics follow `clusterio_<plugin_name>_<metric_nam
|
||||
For metrics that are per-instance, you must define an `instance_id` label and set it accordingly, for example:
|
||||
|
||||
```js
|
||||
import { Counter } from "@clusterio/lib";
|
||||
import { Gauge } from "@clusterio/lib";
|
||||
|
||||
const barMetric = new Gauge(
|
||||
"clusterio_foo_frobber_bar_metric", "Bar instance level",
|
||||
|
||||
Reference in new issue
Block a user