mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-18 15:33:12 +09:00
Add typed hook system for plugins
Replace invokeHook and the per plugin on* methods with AsyncHook collections on the controller, host, instance, clusterioctl and web control objects. Plugin entrypoints export a default function that receives a load context and attaches handlers to the hooks it needs. Class exports still load through fromContext with a deprecation warning. The create templates and docs use the entrypoint function. This is clusterio/clusterio#921 recreated on top of master after the ESM migration and the PluginDeclaration permissions change. Closes #730 Co-Authored-By: Cooldude2606 <25043174+Cooldude2606@users.noreply.github.com> Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
1 parent
8c03ac15ab
commit
7122cbccf8
64 files changed
+1878
-1184
No files matched your search
+18
-28
@@ -16,7 +16,7 @@ import * as lib from "@clusterio/lib";
|
||||
import { ConsoleTransport, levels, logger } from "@clusterio/lib";
|
||||
|
||||
import * as commands from "./src/commands.js";
|
||||
import BaseCtlPlugin from "./src/BaseCtlPlugin.js";
|
||||
import { BaseCtlPlugin, CtlHooks } from "./src/BaseCtlPlugin.js";
|
||||
|
||||
|
||||
/**
|
||||
@@ -53,19 +53,15 @@ class ControlConnector extends lib.WebSocketClientConnector {
|
||||
export class Control extends lib.Link {
|
||||
/** Control config used for connecting to the controller. */
|
||||
config: lib.ControlConfig;
|
||||
/** Mapping of plugin names to their instance for loaded plugins. */
|
||||
plugins: Map<string, BaseCtlPlugin>;
|
||||
/** Keep the control connection alive after the command completes. */
|
||||
keepOpen = false;
|
||||
|
||||
constructor(
|
||||
connector: ControlConnector,
|
||||
controlConfig: lib.ControlConfig,
|
||||
ctlPlugins: Map<string, BaseCtlPlugin>
|
||||
) {
|
||||
super(connector);
|
||||
this.config = controlConfig;
|
||||
this.plugins = ctlPlugins;
|
||||
|
||||
this.handle(lib.LogMessageEvent, this.handleLogMessageEvent.bind(this));
|
||||
this.handle(lib.DebugWsMessageEvent, this.handleDebugWsMessageEvent.bind(this));
|
||||
@@ -105,28 +101,23 @@ export class Control extends lib.Link {
|
||||
}
|
||||
}
|
||||
|
||||
async function loadPlugins(pluginList: Map<string, string>) {
|
||||
async function loadPlugins(pluginList: Map<string, string>, hooks: CtlHooks) {
|
||||
let pluginInfos = await lib.loadPluginInfos(pluginList);
|
||||
lib.registerPluginMessages(pluginInfos);
|
||||
lib.registerPluginPermissions(pluginInfos);
|
||||
lib.addPluginConfigFields(pluginInfos);
|
||||
|
||||
let ctlPlugins = new Map<string, BaseCtlPlugin>();
|
||||
const ctlPlugins = new Set<lib.PluginNodeEnvInfo>();
|
||||
for (let pluginInfo of pluginInfos) {
|
||||
if (!pluginInfo.ctlEntrypoint) {
|
||||
continue;
|
||||
}
|
||||
|
||||
let CtlPlugin = await lib.loadPluginClass(
|
||||
pluginInfo.name,
|
||||
path.posix.join(pluginInfo.requirePath, pluginInfo.ctlEntrypoint),
|
||||
"CtlPlugin",
|
||||
BaseCtlPlugin,
|
||||
);
|
||||
let ctlPlugin = new CtlPlugin(pluginInfo, logger);
|
||||
ctlPlugins.set(pluginInfo.name, ctlPlugin);
|
||||
await ctlPlugin.init();
|
||||
const context = { hooks, logger, plugin: pluginInfo };
|
||||
await lib.loadPlugin(pluginInfo, "ctl", context, "CtlPlugin", BaseCtlPlugin);
|
||||
ctlPlugins.add(pluginInfo);
|
||||
}
|
||||
|
||||
return ctlPlugins;
|
||||
}
|
||||
|
||||
@@ -142,14 +133,14 @@ interface CtlArguments {
|
||||
interface InitializeParameters {
|
||||
args: CtlArguments;
|
||||
shouldRun: boolean;
|
||||
ctlPlugins?: Map<string, BaseCtlPlugin>;
|
||||
ctlHooks: CtlHooks;
|
||||
rootCommands?: lib.CommandTree;
|
||||
controlConfig?: lib.ControlConfig;
|
||||
}
|
||||
|
||||
export async function initialize(
|
||||
argv: string | string[],
|
||||
ctlPlugins?: Map<string, BaseCtlPlugin>,
|
||||
ctlHooks: CtlHooks = new CtlHooks(logger),
|
||||
noLoggerTransport?: boolean,
|
||||
): Promise<InitializeParameters> {
|
||||
// Build a fresh, isolated yargs parser each time this function is called.
|
||||
@@ -208,23 +199,23 @@ export async function initialize(
|
||||
lib.handleUnhandledErrors();
|
||||
}
|
||||
|
||||
// Discover and load plugins. This check exists to allow tests to inject plugins.
|
||||
if (!ctlPlugins || args._[0] === "plugin") {
|
||||
// Discover and load plugins. ctlHooks.size check exists to allow tests to inject plugins.
|
||||
if (ctlHooks.addCommands.size === 0 || args._[0] === "plugin") {
|
||||
logger.verbose(`Loading available plugins from ${args.pluginList}`);
|
||||
const pluginList = await lib.loadPluginList(args.pluginList);
|
||||
|
||||
// If the command is plugin management we don't try to load plugins
|
||||
if (args._[0] === "plugin") {
|
||||
await lib.handlePluginCommand(args, pluginList, args.pluginList);
|
||||
return { args, shouldRun: false };
|
||||
return { args, ctlHooks, shouldRun: false };
|
||||
}
|
||||
|
||||
logger.verbose("Loading Plugins");
|
||||
ctlPlugins = await loadPlugins(pluginList);
|
||||
await loadPlugins(pluginList, ctlHooks);
|
||||
}
|
||||
|
||||
// Add all commands including from plugins and reparse with help and strict checking.
|
||||
const rootCommands = await commands.registerCommands(ctlPlugins, parser);
|
||||
const rootCommands = await commands.registerCommands(ctlHooks, parser);
|
||||
args = parser
|
||||
.help()
|
||||
.strict()
|
||||
@@ -261,10 +252,10 @@ export async function initialize(
|
||||
// Handle the control-config command before trying to connect.
|
||||
if (args._[0] === "control-config") {
|
||||
await lib.handleConfigCommand(args, controlConfig, controlConfigLock);
|
||||
return { args, controlConfig, ctlPlugins, rootCommands, shouldRun: false };
|
||||
return { args, controlConfig, ctlHooks, rootCommands, shouldRun: false };
|
||||
}
|
||||
|
||||
return { args, controlConfig, ctlPlugins, rootCommands, shouldRun: true };
|
||||
return { args, controlConfig, ctlHooks, rootCommands, shouldRun: true };
|
||||
}
|
||||
|
||||
export function selectTargetCommand(args: CtlArguments, rootCommands: lib.CommandTree): lib.Command {
|
||||
@@ -281,11 +272,10 @@ async function startControl() {
|
||||
const {
|
||||
args,
|
||||
shouldRun,
|
||||
ctlPlugins,
|
||||
rootCommands,
|
||||
controlConfig,
|
||||
} = await initialize(process.argv.slice(2));
|
||||
if (!shouldRun || !ctlPlugins || !rootCommands || !controlConfig) {
|
||||
if (!shouldRun || !rootCommands || !controlConfig) {
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -301,7 +291,7 @@ async function startControl() {
|
||||
controlConfig.get("control.controller_token")!,
|
||||
);
|
||||
|
||||
let control = new Control(controlConnector, controlConfig, ctlPlugins);
|
||||
let control = new Control(controlConnector, controlConfig);
|
||||
try {
|
||||
await controlConnector.connect();
|
||||
} catch (err) {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import { bootstrap } from "./ctl.js";
|
||||
export * from "./ctl.js";
|
||||
export { default as BaseCtlPlugin } from "./src/BaseCtlPlugin.js";
|
||||
export { BaseCtlPlugin, CtlHooks, type CtlPluginContext } from "./src/BaseCtlPlugin.js";
|
||||
|
||||
if (import.meta.main) {
|
||||
bootstrap();
|
||||
|
||||
@@ -1,38 +1,18 @@
|
||||
import type { CommandTree, Logger, PluginNodeEnvInfo } from "@clusterio/lib";
|
||||
import * as lib from "@clusterio/lib";
|
||||
|
||||
export type CtlPluginContext = lib.PluginLoadContext<{
|
||||
hooks: CtlHooks
|
||||
}>;
|
||||
|
||||
/**
|
||||
* Base class for clusterioctl plugins
|
||||
*
|
||||
* Ctl plugins are subclasses of this class which get instantiated by
|
||||
* clusterioctl in order to extend its functionallity. To be discovered the
|
||||
* class must be exported under the name `CtlPlugin` in the module
|
||||
* specified by the `ctlEntrypoint` in the plugin's `plugin` export.
|
||||
* Collection of clusterioctl plugin hooks
|
||||
*/
|
||||
export default class BaseCtlPlugin {
|
||||
/**
|
||||
* Logger for this plugin
|
||||
*
|
||||
* Instance of winston Logger for sending log messages from this
|
||||
* plugin. Supported methods and their corresponding log levels are
|
||||
* `error`, `warn`, `audit`, `info` and `verbose`.
|
||||
*/
|
||||
logger: Logger;
|
||||
|
||||
constructor(
|
||||
/**
|
||||
* The plugin's own info module
|
||||
*/
|
||||
public info: PluginNodeEnvInfo,
|
||||
logger: Logger,
|
||||
) {
|
||||
this.logger = logger.child({ plugin: this.info.name }) as unknown as Logger;
|
||||
export class CtlHooks extends lib.AsyncHookCollection {
|
||||
constructor(logger: lib.Logger) {
|
||||
super(logger);
|
||||
this.addCommands = this.newHook();
|
||||
}
|
||||
|
||||
/**
|
||||
* Called immediately after the class is instantiated
|
||||
*/
|
||||
async init() { }
|
||||
|
||||
/**
|
||||
* Called to add commands to the command line interface.
|
||||
*
|
||||
@@ -43,5 +23,47 @@ export default class BaseCtlPlugin {
|
||||
* @param rootCommand -
|
||||
* Root of the clusterioctl command tree.
|
||||
*/
|
||||
async addCommands(rootCommand: CommandTree) { }
|
||||
readonly addCommands: lib.AsyncHook<[rootCommand: lib.CommandTree]>;
|
||||
}
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
|
||||
export interface BaseCtlPlugin {
|
||||
addCommands?(rootCommand: lib.CommandTree): Promise<void>;
|
||||
}
|
||||
|
||||
/**
|
||||
* Base class for clusterioctl plugins
|
||||
*
|
||||
* Ctl plugins are subclasses of this class which get instantiated by
|
||||
* clusterioctl in order to extend its functionallity. To be discovered the
|
||||
* class must be exported under the name `CtlPlugin` in the module
|
||||
* specified by the `ctlEntrypoint` in the plugin's `plugin` export.
|
||||
*/
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
|
||||
export class BaseCtlPlugin {
|
||||
constructor(
|
||||
/**
|
||||
* The plugin's own info module
|
||||
*/
|
||||
public info: lib.PluginNodeEnvInfo,
|
||||
public logger: lib.Logger,
|
||||
private hooks: CtlHooks,
|
||||
) {
|
||||
if (this.addCommands) {
|
||||
hooks.addCommands.attach(info.name, this.addCommands.bind(this));
|
||||
}
|
||||
}
|
||||
|
||||
static fromContext(context: CtlPluginContext) {
|
||||
return new this(context.plugin, context.logger, context.hooks);
|
||||
}
|
||||
|
||||
detachHooks() {
|
||||
this.hooks.detachAll(this.info.name);
|
||||
}
|
||||
|
||||
/**
|
||||
* Called immediately after the class is instantiated
|
||||
*/
|
||||
async init() {}
|
||||
}
|
||||
@@ -1,7 +1,6 @@
|
||||
import type { Argv } from "yargs";
|
||||
|
||||
import * as lib from "@clusterio/lib";
|
||||
import type BaseCtlPlugin from "./BaseCtlPlugin.js";
|
||||
import { controllerCommands } from "./commands_controller.js";
|
||||
import { hostCommands } from "./commands_host.js";
|
||||
import { instanceCommands } from "./commands_instance.js";
|
||||
@@ -12,8 +11,9 @@ import { roleCommands } from "./commands_role.js";
|
||||
import { userCommands } from "./commands_user.js";
|
||||
import { logCommands } from "./commands_log.js";
|
||||
import { debugCommands } from "./commands_debug.js";
|
||||
import type { CtlHooks } from "./BaseCtlPlugin.js";
|
||||
|
||||
export async function registerCommands(ctlPlugins: Map<string, BaseCtlPlugin>, yargs: Argv) {
|
||||
export async function registerCommands(ctlHooks: CtlHooks, yargs: Argv) {
|
||||
const rootCommands = new lib.CommandTree({ name: "clusterioctl", description: "Manage cluster" });
|
||||
rootCommands.add(controllerCommands);
|
||||
rootCommands.add(hostCommands);
|
||||
@@ -26,9 +26,7 @@ export async function registerCommands(ctlPlugins: Map<string, BaseCtlPlugin>, y
|
||||
rootCommands.add(logCommands);
|
||||
rootCommands.add(debugCommands);
|
||||
|
||||
for (let controlPlugin of ctlPlugins.values()) {
|
||||
await controlPlugin.addCommands(rootCommands);
|
||||
}
|
||||
await ctlHooks.addCommands.invoke(rootCommands);
|
||||
|
||||
for (let [name, command] of rootCommands.subCommands) {
|
||||
if (name === command.name) {
|
||||
|
||||
Reference in new issue
Block a user