Add UnavailableError and keep the PermissionError name

Host not connected, host shutting down and instance not running are
now UnavailableError (503) instead of ConflictError. The request error
migration notes move to a new 2.1 guide, since this ships in 2.1.

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 1c7c00b033
commit 54e9340e61
23 files changed
+78 -66

No files matched your search

+3 -3
View File
@@ -431,12 +431,12 @@ export default class ControlConnection extends BaseConnection {
// Check connectivity
let sourceHostConnection = this._controller.wsServer.hostConnections.get(sourceHostId);
if (!sourceHostConnection || sourceHostConnection.connector.closing) {
throw new lib.ConflictError("Source host is not connected to the controller");
throw new lib.UnavailableError("Source host is not connected to the controller");
}
let targetHostConnection = this._controller.wsServer.hostConnections.get(targetHostId);
if (!targetHostConnection || targetHostConnection.connector.closing) {
throw new lib.ConflictError("Target host is not connected to the controller");
throw new lib.UnavailableError("Target host is not connected to the controller");
}
// Create stream to proxy from target to source
@@ -997,7 +997,7 @@ export default class ControlConnection extends BaseConnection {
async handleNoteSetRequest(request: lib.NoteSetRequest) {
const { resourceType, resourceId, content } = request;
if (!resourceType || !resourceId) {
throw new lib.RequestError("resourceType and resourceId must not be empty");
throw new lib.ValidationError("resourceType and resourceId must not be empty");
}
this._controller.setNote(resourceType, resourceId, content, this.user.name);
}
+3 -3
View File
@@ -1476,13 +1476,13 @@ export default class Controller {
}
connection = this.wsServer.hostConnections.get(hostId);
if (!connection) {
throw new lib.ConflictError("Host containing instance is not connected");
throw new lib.UnavailableError("Host containing instance is not connected");
}
} else if (dst.type === lib.Address.host) {
connection = this.wsServer.hostConnections.get(dst.id);
if (!connection) {
throw new lib.ConflictError("Host is not connected");
throw new lib.UnavailableError("Host is not connected");
}
} else {
@@ -1570,7 +1570,7 @@ export default class Controller {
}
let connection = this.wsServer.hostConnections.get(hostId);
if (!connection) {
throw new lib.ConflictError("Host containing instance is not connected");
throw new lib.UnavailableError("Host containing instance is not connected");
}
return await connection.send(request);
}
+1 -1
View File
@@ -74,7 +74,7 @@ export default class ControllerRouter {
return false;
}
origin.connector.sendResponseError(
new lib.ResponseError(msg || "Unroutable destination", "ConflictError"), message.src
new lib.ResponseError(msg || "Unroutable destination", "UnavailableError"), message.src
);
return true;
}
+2 -2
View File
@@ -173,7 +173,7 @@ export default class InstanceManager {
* the instance will be unassigned.
*
* @throws {module:lib.NotFoundError} if the instance does not exist.
* @throws {module:lib.ConflictError} if the target host is not connected.
* @throws {module:lib.UnavailableError} if the target host is not connected.
*/
async assignInstance(
instanceId: number,
@@ -191,7 +191,7 @@ export default class InstanceManager {
if (hostId !== null) {
newHostConnection = hostConnections.get(hostId);
if (!newHostConnection) {
throw new lib.ConflictError("Target host is not connected to the controller");
throw new lib.UnavailableError("Target host is not connected to the controller");
}
}
+2 -2
View File
@@ -1,7 +1,7 @@
import {
IUser, Role, SubscribableDatastore,
PermissionDeniedError, PermissionName, permissions,
PermissionError, PermissionName, permissions,
} from "@clusterio/lib";
import UserRecord from "./UserRecord.js";
@@ -141,6 +141,6 @@ export default class User extends UserRecord implements IUser {
}
}
throw new PermissionDeniedError("Permission denied");
throw new PermissionError("Permission denied");
}
}
+1 -1
View File
@@ -307,7 +307,7 @@ async function startCtl() {
logger.error(`Error running command: ${err.message}`);
process.exitCode = 1;
} else if (err instanceof lib.ClientError) {
} else if (err instanceof lib.ClientError || err instanceof lib.UnavailableError) {
logger.error(`Error sending request: ${err.message}`);
process.exitCode = 1;
+2 -2
View File
@@ -203,7 +203,7 @@ export class HostRouter {
return false;
}
origin.connector.sendResponseError(
new lib.ResponseError(msg || "Instance is not running.", "ConflictError"), message.src
new lib.ResponseError(msg || "Instance is not running.", "UnavailableError"), message.src
);
}
return true;
@@ -271,7 +271,7 @@ export class HostRouter {
}
if (this.host._shuttingDown) {
origin.connector.sendResponseError(
new lib.ResponseError("Host is shutting down.", "ConflictError"), message.src
new lib.ResponseError("Host is shutting down.", "UnavailableError"), message.src
);
return;
}
+2 -2
View File
@@ -1422,7 +1422,7 @@ end`.replace(/\r?\n/g, " ");
async handleInstanceSaveGameRequest() {
if (this._status !== "running") {
throw new lib.ConflictError("Instance is not running");
throw new lib.UnavailableError("Instance is not running");
}
const saved = new Promise<void>((resolve, reject) => {
@@ -1432,7 +1432,7 @@ end`.replace(/\r?\n/g, " ");
};
const onExit = () => {
this.server.off("save-finished", onSaved);
reject(new lib.ConflictError("Instance stopped before the save finished"));
reject(new lib.UnavailableError("Instance stopped before the save finished"));
};
this.server.once("save-finished", onSaved);
this.server.once("exit", onExit);
+1 -1
View File
@@ -162,7 +162,7 @@ export interface IUser extends UserDetails {
*
* @param permission - The permission to check for.
* @throws {Error} If the given permission does not exist.
* @throws {libErrors.PermissionDeniedError} if the user does noh have the given permission.
* @throws {libErrors.PermissionError} if the user does noh have the given permission.
*/
checkPermission(permission: PermissionName): void
}
+8 -2
View File
@@ -49,7 +49,7 @@ export class ForbiddenError extends ClientError { }
/**
* Thrown when a permission check fails
*/
export class PermissionDeniedError extends ForbiddenError { }
export class PermissionError extends ForbiddenError { }
/**
* Thrown when a config field is not accessible from the current location
@@ -68,7 +68,7 @@ export class TimeoutError extends ClientError { }
/**
* Thrown when the request conflicts with the current state, such as an
* instance that is running or a host that is not connected (HTTP 409)
* instance that is running or a name that is taken (HTTP 409)
*/
export class ConflictError extends ClientError { }
@@ -84,6 +84,12 @@ export class ServerError extends Error { }
*/
export class InternalServerError extends ServerError { }
/**
* Thrown when the host or instance that should handle the request is not
* connected, not running or shutting down (HTTP 503)
*/
export class UnavailableError extends ServerError { }
/**
* Signal for messages that fail validation
*/
+1 -1
View File
@@ -348,7 +348,7 @@ export class Link {
*
* @param message - Message to check.
* @param entry - Request or Event entry for this Message.
* @throws {libErrors.PermissionDeniedError} if unauthorized.
* @throws {libErrors.PermissionError} if unauthorized.
*/
validatePermission(message: libData.MessageRequest | libData.MessageEvent, entry: RequestEntry | EventEntry) { }
+2 -1
View File
@@ -164,13 +164,14 @@ export const errorClasses: ErrorClass[] = [
errors.InvalidValueError,
errors.InvalidFieldError,
errors.ForbiddenError,
errors.PermissionDeniedError,
errors.PermissionError,
errors.InvalidAccessError,
errors.NotFoundError,
errors.TimeoutError,
errors.ConflictError,
errors.ServerError,
errors.InternalServerError,
errors.UnavailableError,
errors.InvalidMessage,
errors.SessionLost,
];