diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md index e64bee9c..cbc36a4b 100644 --- a/docs/managing-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -13,14 +13,17 @@ The easiest way to do this is to run `npx clusteriocontroller bootstrap create-c ctl> --output json 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": "", "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 diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index 2a0d4e33..d7cf7d6d 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -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": "", "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": "", "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: diff --git a/packages/ctl/README.md b/packages/ctl/README.md index 91ee0c14..cf9fc7be 100644 --- a/packages/ctl/README.md +++ b/packages/ctl/README.md @@ -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 ` Format to print the results of cluster commands in. + * `--output ` 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. diff --git a/packages/ctl/ctl.ts b/packages/ctl/ctl.ts index 152a8285..70792252 100755 --- a/packages/ctl/ctl.ts +++ b/packages/ctl/ctl.ts @@ -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 | +---------------------------------+ diff --git a/packages/ctl/src/command_ops.ts b/packages/ctl/src/command_ops.ts index 1d2eea0d..5cdf8e99 100644 --- a/packages/ctl/src/command_ops.ts +++ b/packages/ctl/src/command_ops.ts @@ -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")); } } } diff --git a/packages/ctl/src/commands_host.ts b/packages/ctl/src/commands_host.ts index 92c825c7..e3672d09 100644 --- a/packages/ctl/src/commands_host.ts +++ b/packages/ctl/src/commands_host.ts @@ -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({ diff --git a/packages/ctl/src/commands_instance.ts b/packages/ctl/src/commands_instance.ts index 93ebc965..f469e13a 100644 --- a/packages/ctl/src/commands_instance.ts +++ b/packages/ctl/src/commands_instance.ts @@ -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) { diff --git a/packages/ctl/src/commands_note.ts b/packages/ctl/src/commands_note.ts index 7a78fc7b..21dd41bd 100644 --- a/packages/ctl/src/commands_note.ts +++ b/packages/ctl/src/commands_note.ts @@ -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, - }))); + }))))); }, })); diff --git a/packages/ctl/src/commands_user.ts b/packages/ctl/src/commands_user.ts index 169f03fa..434e5a8b 100644 --- a/packages/ctl/src/commands_user.ts +++ b/packages/ctl/src/commands_user.ts @@ -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))); }, })); diff --git a/packages/ctl/src/config_ops.ts b/packages/ctl/src/config_ops.ts index d264297d..45c6c831 100644 --- a/packages/ctl/src/config_ops.ts +++ b/packages/ctl/src/config_ops.ts @@ -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)}`); } diff --git a/plugins/player_sync/ctl.ts b/plugins/player_sync/ctl.ts index 18cee8c6..8932d953 100644 --- a/plugins/player_sync/ctl.ts +++ b/plugins/player_sync/ctl.ts @@ -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}`); + } + } + }); }, })); diff --git a/test/ctl/command_ops.test.js b/test/ctl/command_ops.test.js index 34ad90a2..175318bd 100644 --- a/test/ctl/command_ops.test.js +++ b/test/ctl/command_ops.test.js @@ -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()), []); diff --git a/test/integration/clusterio.js b/test/integration/clusterio.js index 2bdd6ed7..091319b7 100644 --- a/test/integration/clusterio.js +++ b/test/integration/clusterio.js @@ -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"));