mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-21 08:03:13 +09:00
Address review of ctl --output
Add a wire output format that prints the toJSON format sent over the link. Commands without a result print {"success": true}, or "Command ran successfully" in human mode. The missing URL check throws a StartupError, unexpected command errors are rethrown to the startup handler, and startup errors log as fatal. user list, note list and host plugin list print the objects they received instead of their table rows.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
10beffe167
commit
8550df69eb
13 files changed
+131
-112
No files matched your search
@@ -13,14 +13,17 @@ The easiest way to do this is to run `npx clusteriocontroller bootstrap create-c
|
||||
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 `{}`.
|
||||
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 both formats.
|
||||
Log messages, including the error message, 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`.
|
||||
The default is `--output human`, which prints `Command ran successfully` for commands that have no result.
|
||||
|
||||
|
||||
## Hosts
|
||||
|
||||
@@ -981,9 +981,10 @@ handler: async function(args, ctl) {
|
||||
},
|
||||
```
|
||||
|
||||
`ctl.output.result(data, human)` prints `data` as JSON in json mode and calls `human` otherwise.
|
||||
`ctl.output.result(data, human)` prints `data` as JSON in json and wire mode and calls `human` otherwise.
|
||||
`ctl.output.table(rows)` prints an array of objects as a table or as a JSON array.
|
||||
Commands that print nothing get `{}` printed for them in json mode, and errors thrown from the handler are printed as `{"error": "<ClassName>", "message": "<message>"}`.
|
||||
`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:
|
||||
|
||||
|
||||
@@ -23,9 +23,9 @@ 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>` Format to print the results of cluster commands in.
|
||||
* `--output <human|json|wire>` Format to print the results of cluster commands in.
|
||||
Defaults to `human`.
|
||||
See [Output format](/docs/managing-a-cluster.md#output-format) for what `json` prints.
|
||||
See [Output format](/docs/managing-a-cluster.md#output-format) for what `json` and `wire` print.
|
||||
The `plugin` and `config` commands described below always print human readable text.
|
||||
|
||||
|
||||
|
||||
+23
-32
@@ -85,8 +85,9 @@ export class Ctl extends lib.Link {
|
||||
}
|
||||
|
||||
async handleLogMessageEvent(event: lib.LogMessageEvent) {
|
||||
if (this.output.json && this.output.streaming) {
|
||||
this.output.result(event.info);
|
||||
// Only streaming commands print log events as results, the rest log them to stderr
|
||||
if (this.output.streaming) {
|
||||
this.output.result(event.info, () => logger.log(event.info as any));
|
||||
} else {
|
||||
logger.log(event.info as any);
|
||||
}
|
||||
@@ -292,27 +293,30 @@ export async function runCommand(
|
||||
link.output.finish();
|
||||
}
|
||||
|
||||
async function startCtl(output: CommandOutput) {
|
||||
async function startCtl() {
|
||||
const {
|
||||
args,
|
||||
shouldRun,
|
||||
rootCommands,
|
||||
ctlConfig,
|
||||
} = await initialize(process.argv.slice(2));
|
||||
output.format = args.output;
|
||||
if (!shouldRun || !rootCommands || !ctlConfig) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (!ctlConfig.get("ctl.controller_url") || !ctlConfig.get("ctl.controller_token")) {
|
||||
const message = "Missing URL and/or token to connect with. See README.md for setting up access.";
|
||||
if (output.json) {
|
||||
output.error(new lib.StartupError(message));
|
||||
} else {
|
||||
logger.error(message);
|
||||
try {
|
||||
await connectAndRun(args, rootCommands, ctlConfig);
|
||||
} catch (err) {
|
||||
if (args.output !== "human") {
|
||||
new CommandOutput(args.output).error(err);
|
||||
}
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
async function connectAndRun(args: CtlArguments, rootCommands: lib.CommandTree, ctlConfig: lib.CtlConfig) {
|
||||
if (!ctlConfig.get("ctl.controller_url") || !ctlConfig.get("ctl.controller_token")) {
|
||||
throw new lib.StartupError("Missing URL and/or token to connect with. See README.md for setting up access.");
|
||||
}
|
||||
|
||||
let controlConnector = new CtlConnector(
|
||||
@@ -340,30 +344,22 @@ async function startCtl(output: CommandOutput) {
|
||||
|
||||
} catch (err) {
|
||||
ctl.keepOpen = false;
|
||||
const expected = err instanceof lib.CommandError || err instanceof lib.ClientError
|
||||
|| err instanceof lib.ServerError;
|
||||
if (ctl.output.json) {
|
||||
ctl.output.error(err);
|
||||
process.exitCode = 1;
|
||||
if (!expected) {
|
||||
logger.error((err as Error).stack ?? String(err));
|
||||
}
|
||||
|
||||
} else if (err instanceof lib.CommandError) {
|
||||
if (err instanceof lib.CommandError) {
|
||||
logger.error(`Error running command: ${err.message}`);
|
||||
process.exitCode = 1;
|
||||
|
||||
} else if (err instanceof lib.ClientError || err instanceof lib.UnavailableError) {
|
||||
logger.error(`Error sending request: ${err.message}`);
|
||||
process.exitCode = 1;
|
||||
|
||||
} else if (err instanceof lib.ServerError) {
|
||||
logger.error(`Error sending request:\n${err.stack ?? err.message}`);
|
||||
process.exitCode = 1;
|
||||
|
||||
} else {
|
||||
throw err;
|
||||
}
|
||||
if (!ctl.output.human) {
|
||||
ctl.output.error(err);
|
||||
}
|
||||
process.exitCode = 1;
|
||||
|
||||
} finally {
|
||||
if (!ctl.keepOpen) {
|
||||
@@ -373,13 +369,8 @@ async function startCtl(output: CommandOutput) {
|
||||
}
|
||||
|
||||
export function bootstrap() {
|
||||
const output = new CommandOutput();
|
||||
startCtl(output).catch(err => {
|
||||
startCtl().catch(err => {
|
||||
process.exitCode = 1;
|
||||
if (output.json) {
|
||||
output.error(err);
|
||||
return;
|
||||
}
|
||||
if (err.errors) {
|
||||
logger.fatal(JSON.stringify(err.errors, null, "\t"));
|
||||
}
|
||||
@@ -392,7 +383,7 @@ export function bootstrap() {
|
||||
${err.stack}`
|
||||
);
|
||||
} else {
|
||||
logger.error(`
|
||||
logger.fatal(`
|
||||
+---------------------------------+
|
||||
| Unable to to start clusterioctl |
|
||||
+---------------------------------+
|
||||
|
||||
@@ -39,13 +39,25 @@ export function errorToJson(err: unknown) {
|
||||
return { error: "Error", message: String(err) };
|
||||
}
|
||||
|
||||
export const outputFormats = ["human", "json"] as const;
|
||||
/** 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 mode each call to result prints one line of JSON to stdout.
|
||||
* 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 */
|
||||
@@ -57,26 +69,28 @@ export class CommandOutput {
|
||||
public format: OutputFormat = "human",
|
||||
) { }
|
||||
|
||||
get json() {
|
||||
return this.format === "json";
|
||||
get human() {
|
||||
return this.format === "human";
|
||||
}
|
||||
|
||||
/**
|
||||
* Print the result of a command
|
||||
*
|
||||
* @param data - Printed as JSON in json mode.
|
||||
* @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.json) {
|
||||
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 mode */
|
||||
/** Print a list of objects as a table, or as an array in json and wire mode */
|
||||
table(rows: object[]) {
|
||||
this.result(rows, () => print(asTable(rows)));
|
||||
}
|
||||
@@ -87,10 +101,10 @@ export class CommandOutput {
|
||||
print(JSON.stringify(errorToJson(err)));
|
||||
}
|
||||
|
||||
/** Print `{}` in json mode for commands that finished without printing a result */
|
||||
/** Print a success result for commands that finished without printing one */
|
||||
finish() {
|
||||
if (this.json && !this.written && !this.streaming) {
|
||||
this.result({});
|
||||
if (!this.written && !this.streaming) {
|
||||
this.result({ success: true }, () => print("Command ran successfully"));
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -287,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());
|
||||
ctl.output.table(plugins.map(p => ({
|
||||
ctl.output.result(plugins, () => print(asTable(plugins.map(p => ({
|
||||
title: p.title, version: p.version, state: p.state, npmPackage: p.npmPackage,
|
||||
})));
|
||||
})))));
|
||||
},
|
||||
}));
|
||||
hostPluginCommands.add(new lib.Command({
|
||||
|
||||
@@ -575,7 +575,7 @@ instanceCommands.add(new lib.Command({
|
||||
return;
|
||||
}
|
||||
|
||||
const human = !ctl.output.json;
|
||||
const human = ctl.output.human;
|
||||
if (human) {
|
||||
print(`Starting ${instancesToStart.length} instance(s):`);
|
||||
for (const instance of instancesToStart) {
|
||||
@@ -662,7 +662,7 @@ instanceCommands.add(new lib.Command({
|
||||
return;
|
||||
}
|
||||
|
||||
const human = !ctl.output.json;
|
||||
const human = ctl.output.human;
|
||||
if (human) {
|
||||
print(`Stopping ${instancesToStop.length} instance(s):`);
|
||||
for (const instance of instancesToStop) {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
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";
|
||||
|
||||
export const noteCommands = new lib.CommandTree({
|
||||
name: "note", description: "Notes attached to hosts, instances, users and other resources",
|
||||
@@ -16,12 +16,12 @@ noteCommands.add(new lib.Command({
|
||||
if (args.type !== undefined) {
|
||||
notes = notes.filter(note => note.resourceType === args.type);
|
||||
}
|
||||
ctl.output.table(notes.map(note => ({
|
||||
ctl.output.result(notes, () => print(asTable(notes.map(note => ({
|
||||
type: note.resourceType,
|
||||
id: note.resourceId,
|
||||
updatedBy: note.updatedBy,
|
||||
content: note.content,
|
||||
})));
|
||||
})))));
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -55,29 +55,18 @@ 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;
|
||||
}
|
||||
}
|
||||
ctl.output.table(users);
|
||||
const users = await ctl.send(new lib.UserListRequest());
|
||||
const rows = users.map(user => {
|
||||
const {
|
||||
playerStats, isDeleted, banReason, instanceStats, isAdmin, isWhitelisted, isBanned, ...row
|
||||
} = user;
|
||||
return {
|
||||
...row,
|
||||
...args.attributes && { isAdmin, isWhitelisted, isBanned },
|
||||
...args.stats && playerStats,
|
||||
};
|
||||
});
|
||||
ctl.output.result(users, () => print(asTable(rows)));
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -60,6 +60,7 @@ export function serializedConfigToString(
|
||||
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)}`);
|
||||
}
|
||||
|
||||
+30
-30
@@ -30,7 +30,7 @@ playerSyncCommands.add(new lib.Command({
|
||||
handler: async function(args: object, ctl: Ctl) {
|
||||
let players = await ctl.send(new msg.ListPlayersRequest());
|
||||
players.sort((a, b) => a.name.localeCompare(b.name));
|
||||
if (ctl.output.json) {
|
||||
if (!ctl.output.human) {
|
||||
ctl.output.result(players);
|
||||
return;
|
||||
}
|
||||
@@ -54,36 +54,36 @@ playerSyncCommands.add(new lib.Command({
|
||||
handler: async function(args: { player: string }, ctl: Ctl) {
|
||||
let response = await ctl.send(new msg.GetPlayerDataRequest(args.player));
|
||||
let playerData = response.playerData;
|
||||
if (ctl.output.json) {
|
||||
ctl.output.result({
|
||||
instanceId: response.instanceId,
|
||||
...playerData && {
|
||||
generation: playerData.generation,
|
||||
size: JSON.stringify(playerData).length,
|
||||
controller: playerData.controller,
|
||||
force: playerData.force,
|
||||
inventories: summarizePlayerInventories(playerData),
|
||||
},
|
||||
});
|
||||
return;
|
||||
}
|
||||
print(`acquired by: ${await instanceName(ctl, response.instanceId)}`);
|
||||
if (!playerData) {
|
||||
print(`No player data stored for ${args.player}`);
|
||||
return;
|
||||
}
|
||||
print(`generation: ${playerData.generation}`);
|
||||
print(`size: ${lib.formatBytes(JSON.stringify(playerData).length)}`);
|
||||
print(`controller: ${playerData.controller}`);
|
||||
print(`force: ${playerData.force}`);
|
||||
for (let inventory of summarizePlayerInventories(playerData)) {
|
||||
print(`${inventory.name}:`);
|
||||
for (let item of inventory.items) {
|
||||
let quality = item.quality ? ` (${item.quality})` : "";
|
||||
let size = item.exportSize ? ` ${lib.formatBytes(item.exportSize)}` : "";
|
||||
print(` ${item.count} ${item.name}${quality}${size}`);
|
||||
const summary = {
|
||||
instanceId: response.instanceId,
|
||||
...playerData && {
|
||||
generation: playerData.generation,
|
||||
size: JSON.stringify(playerData).length,
|
||||
controller: playerData.controller,
|
||||
force: playerData.force,
|
||||
inventories: summarizePlayerInventories(playerData),
|
||||
},
|
||||
};
|
||||
const acquiredBy = ctl.output.human ? await instanceName(ctl, response.instanceId) : "";
|
||||
ctl.output.result(summary, () => {
|
||||
print(`acquired by: ${acquiredBy}`);
|
||||
if (!playerData) {
|
||||
print(`No player data stored for ${args.player}`);
|
||||
return;
|
||||
}
|
||||
}
|
||||
print(`generation: ${summary.generation}`);
|
||||
print(`size: ${lib.formatBytes(summary.size!)}`);
|
||||
print(`controller: ${summary.controller}`);
|
||||
print(`force: ${summary.force}`);
|
||||
for (let inventory of summary.inventories!) {
|
||||
print(`${inventory.name}:`);
|
||||
for (let item of inventory.items) {
|
||||
let quality = item.quality ? ` (${item.quality})` : "";
|
||||
let size = item.exportSize ? ` ${lib.formatBytes(item.exportSize)}` : "";
|
||||
print(` ${item.count} ${item.name}${quality}${size}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
},
|
||||
}));
|
||||
|
||||
|
||||
@@ -43,6 +43,9 @@ describe("ctl/command_ops", function() {
|
||||
assert.deepEqual(captureLog(() => output.result({ a: 1 }, human)), ["human"]);
|
||||
assert.deepEqual(captureLog(() => output.finish()), []);
|
||||
});
|
||||
it("prints a success line in human mode for commands without a result", function() {
|
||||
assert.deepEqual(captureLog(() => new CommandOutput("human").finish()), ["Command ran successfully"]);
|
||||
});
|
||||
it("prints one line of JSON per result in json mode", function() {
|
||||
const output = new CommandOutput("json");
|
||||
const lines = captureLog(() => {
|
||||
@@ -52,8 +55,14 @@ describe("ctl/command_ops", function() {
|
||||
});
|
||||
assert.deepEqual(lines, ['{"a":[1]}', '[{"b":2}]']);
|
||||
});
|
||||
it("prints {} for commands without a result", function() {
|
||||
assert.deepEqual(captureLog(() => new CommandOutput("json").finish()), ["{}"]);
|
||||
it("prints the toJSON format in wire mode", function() {
|
||||
const output = new CommandOutput("wire");
|
||||
const role = new lib.Role(1, "name", "desc", new Set(["core.admin"]));
|
||||
const lines = captureLog(() => output.result({ role, set: new Set([1]), map: new Map([["a", 2]]) }));
|
||||
assert.deepEqual(JSON.parse(lines[0]), { role: JSON.parse(JSON.stringify(role)), set: [1], map: { a: 2 } });
|
||||
});
|
||||
it("prints success for commands without a result", function() {
|
||||
assert.deepEqual(captureLog(() => new CommandOutput("json").finish()), ['{"success":true}']);
|
||||
const streaming = new CommandOutput("json");
|
||||
streaming.streaming = true;
|
||||
assert.deepEqual(captureLog(() => streaming.finish()), []);
|
||||
|
||||
@@ -2326,7 +2326,18 @@ describe("Integration of Clusterio", function() {
|
||||
const { id } = JSON.parse(await execCtlOutput("--output json role create json-role"));
|
||||
const roles = await getControl().send(new lib.RoleListRequest());
|
||||
assert.equal(roles.find(role => role.id === id)?.name, "json-role");
|
||||
assert.equal(await execCtlOutput(`--output json role delete ${id}`), "{}");
|
||||
assert.equal(await execCtlOutput(`--output json role delete ${id}`), '{"success":true}');
|
||||
});
|
||||
it("prints the toJSON format in wire mode", async function() {
|
||||
const [jsonUser] = JSON.parse(await execCtlOutput("--output json user list"));
|
||||
const [wireUser] = JSON.parse(await execCtlOutput("--output wire user list"));
|
||||
assert("roleIds" in jsonUser);
|
||||
assert(!("roleIds" in wireUser));
|
||||
assert.equal(wireUser.name, jsonUser.name);
|
||||
});
|
||||
it("prints a success line for commands without a result", async function() {
|
||||
const { id } = JSON.parse(await execCtlOutput("--output json role create human-role"));
|
||||
assert.equal(await execCtlOutput(`role delete ${id}`), "Command ran successfully");
|
||||
});
|
||||
it("prints log queries as an array", async function() {
|
||||
const log = JSON.parse(await execCtlOutput("--output json log query --controller --limit 1"));
|
||||
|
||||
Reference in new issue
Block a user