Keep error classes across links

Error responses now carry the registered name of the thrown error's
class, and the requester rejects with an instance of that class instead
of a generic RequestError. Error classes are registered like message
classes, and plugins list their own in `errors`.

RequestError is replaced by a hierarchy following the HTTP status codes:
ClientError (ValidationError, ForbiddenError, NotFoundError,
TimeoutError, ConflictError) and ServerError (InternalServerError).
PermissionError is PermissionDeniedError and the config errors
InvalidValue, InvalidField and InvalidAccess gain an Error suffix.

Link logs only errors whose class is not registered. These arrive on the
other side as InternalServerError with the original message and stack,
so an error forwarded through the controller is logged once, where it
was thrown.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
bbassieandClaude Opus 5.5 committed 2026-10-27 22:03:13 +00:00
1 parent ffe82f81d8
commit 1c7c00b033
37 files changed
+589 -310

No files matched your search

+1
View File
@@ -43,6 +43,7 @@ Plugin classes also supply a `plugin` name.
`Link.register` registers request and event classes and compiles their payload validators.
Core classes are registered by the link module; `registerPluginMessages` registers each plugin's `messages` array.
It also registers the plugin's `errors` array with `Link.registerError`, so an error thrown by a request handler is rejected on the requester as the same class.
Incoming messages invoke handlers attached with `link.handle(MessageClass, handler)`.
Plugins attach these handlers from their entrypoint functions rather than relying on method-name conventions.
+1 -1
View File
@@ -116,7 +116,7 @@ E.g.:
let value = configInstance.fields["group.field"]
The set method also takes an extra argument, which is the value to set the field to.
If the value is not valid this will throw an InvalidValue exception, if the field doesn't exist it will throw an InvalidField exception.
If the value is not valid this will throw an InvalidValueError exception, if the field doesn't exist it will throw an InvalidFieldError exception.
## Config Lifecycle
+24
View File
@@ -305,6 +305,30 @@ The remaining uses of "control" for clusterioctl were renamed to "ctl":
The term "control" is still used in message `src` and `dst` and in config field locations, where it covers both ctl and the web interface.
## 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, host not connected, name taken etc.: `ConflictError`.
- 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`.
Other renames:
- `PermissionError` is `PermissionDeniedError`.
- `lib.InvalidValue`, `lib.InvalidField` and `lib.InvalidAccess` are `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.
## Static assets in the web interface
`staticRoot` now includes the `static/` prefix.
+2 -1
View File
@@ -223,7 +223,8 @@ Plugins may define their own requests as well.
- `src: Address` - Responding endpoint.
- `dst: Address` - Requester's address, including the original request ID.
- `data.message: string` - Human-readable error description.
- `data.code: string` (optional) - Error code.
- `data.code: string` (optional) - Registered name of the error class, `<plugin>:<class>` for plugin errors.
Missing or unknown names are received as `InternalServerError`.
- `data.stack: string` (optional) - Error stack.
+54 -3
View File
@@ -154,6 +154,10 @@ The following properties are recognized:
Array of request and event classes for this plugin.
See guide for [defining link messages](#defining-link-messages) below.
**errors**:
Array of error classes for this plugin.
See [Request errors](#request-errors).
**permissions**:
Array of permission definitions for this plugin.
See [Plugin Permissions](#plugin-permissions)
@@ -641,16 +645,16 @@ 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.
Check any required payload shape before inspecting fields, and use `user.checkPermission(...)` or throw a `ClientError` such as `PermissionDeniedError` 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";
import { ValidationError } 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");
throw new ValidationError("Expected a boolean special field");
}
user.checkPermission(data.special ? "foo_frobber.special" : "foo_frobber.frobnicate");
}
@@ -740,6 +744,53 @@ connection.sendTo({ instanceId: 123 }, message);
connection.sendTo({ controlId: 123 }, message);
```
### Request errors
An error thrown by a request handler is sent back to the requester, and the promise returned by `.sendTo()` rejects with an instance of the same class.
The error classes follow the HTTP status codes:
```
Error
├── ClientError (4xx)
│ ├── ValidationError (400)
│ │ ├── InvalidValueError
│ │ └── InvalidFieldError
│ ├── ForbiddenError (403)
│ │ ├── PermissionDeniedError
│ │ └── InvalidAccessError
│ ├── NotFoundError (404)
│ ├── TimeoutError (408)
│ └── ConflictError (409)
└── ServerError (5xx)
└── InternalServerError (500)
```
Throw a `ClientError` subclass when the request can't be done as asked, for example:
```js
controller.handle(messages.Frobnicate, async request => {
if (!frobnicators.has(request.id)) {
throw new lib.NotFoundError(`Frobnicator ${request.id} does not exist`);
}
// ...
});
```
Errors of a class that is not registered are logged as unexpected by the side that threw them and are received as `InternalServerError`.
Registered errors are not logged.
The message and stack trace of the original error are kept in both cases.
Plugins can define their own error classes by listing them in `errors` of the plugin declaration.
They need a static `plugin` property set to the plugin name and must take the message as the first constructor argument:
```js
export class FrobnicatorJammed extends lib.ConflictError {
static plugin = "foo_frobber";
}
```
A subclass that is not registered is received as its closest registered parent class.
### Handling connection events
There are a few connection related events that plugins neeed to repsond to in order to avoid data loss and connection problems.