mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-16 15:30:41 +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
@@ -1,6 +1,6 @@
|
||||
import type React from "react";
|
||||
import type { AccountRole, FieldDefinition, Logger, PermissionName, PluginWebpackEnvInfo } from "@clusterio/lib";
|
||||
import type { Control } from "./util/websocket";
|
||||
import * as lib from "@clusterio/lib";
|
||||
|
||||
/**
|
||||
* Plugin supplied login form
|
||||
@@ -23,25 +23,17 @@ export interface PluginLoginForm {
|
||||
Component: React.ComponentType<{ setToken(token: string): void }>;
|
||||
}
|
||||
|
||||
export interface InputComponentProps {
|
||||
disabled?: boolean,
|
||||
fieldDefinition: FieldDefinition,
|
||||
value: null | boolean | number | string,
|
||||
onChange: (value: null | boolean | number | string) => void,
|
||||
}
|
||||
export type InputComponent = React.ComponentType<InputComponentProps>;
|
||||
|
||||
export type UserAccount = {
|
||||
/** Name of the currently logged in account. */
|
||||
name: string;
|
||||
/** Roles of the corrently logged in account. */
|
||||
roles: AccountRole[];
|
||||
/** Roles of the currently logged in account. */
|
||||
roles: lib.AccountRole[];
|
||||
/** Check if the currently logged in account has the given permission. */
|
||||
hasPermission: (permission: PermissionName) => boolean | null;
|
||||
hasPermission: (permission: lib.PermissionName) => boolean | null;
|
||||
/** Check if the currently logged in account has any of the given permissions. */
|
||||
hasAnyPermission: (...permissions: PermissionName[]) => boolean | null;
|
||||
hasAnyPermission: (...permissions: lib.PermissionName[]) => boolean | null;
|
||||
/** Check if the currently logged in account has all of given permissions. */
|
||||
hasAllPermission: (...permissions: PermissionName[]) => boolean | null;
|
||||
hasAllPermission: (...permissions: lib.PermissionName[]) => boolean | null;
|
||||
/** Logs out of the web interface. */
|
||||
logOut: () => void;
|
||||
};
|
||||
@@ -75,109 +67,91 @@ export interface PluginPage {
|
||||
/**
|
||||
* Permission to access page. function are expected to throw an error if access is deny.
|
||||
*/
|
||||
permission?: PermissionName | ((account: UserAccount) => (boolean|null));
|
||||
permission?: lib.PermissionName | ((account: UserAccount) => (boolean|null));
|
||||
};
|
||||
|
||||
/**
|
||||
* Base class for web interface plugins
|
||||
*/
|
||||
export default class BaseWebPlugin {
|
||||
export interface InputComponentProps {
|
||||
disabled?: boolean,
|
||||
fieldDefinition: lib.FieldDefinition,
|
||||
value: null | boolean | number | string,
|
||||
onChange: (value: null | boolean | number | string) => void,
|
||||
}
|
||||
|
||||
export type InputComponent = React.ComponentType<InputComponentProps>;
|
||||
|
||||
export type ExtensionSlotProps = {
|
||||
/** Placed at the end of the overview page. */
|
||||
OverviewPage: Record<never, never>;
|
||||
/** Placed at the end of the controller page. */
|
||||
ControllerPage: Record<never, never>;
|
||||
/** Placed at the end of the hosts list page. */
|
||||
HostsPage: Record<never, never>;
|
||||
/**
|
||||
* Contents of the plugin's package.json file
|
||||
* Placed at the end of each host page.
|
||||
* `host` is the host the page is displayed for.
|
||||
*/
|
||||
HostViewPage: {
|
||||
host: lib.HostDetails;
|
||||
};
|
||||
/** Placed at the end of the instance list page. */
|
||||
InstancesPage: Record<never, never>;
|
||||
/**
|
||||
* Placed at the end of each instance page.
|
||||
* `instance` is the instance the page is displayed for.
|
||||
*/
|
||||
InstanceViewPage: {
|
||||
instance: lib.InstanceDetails;
|
||||
};
|
||||
/** Placed at the end of the users list page. */
|
||||
UsersPage: Record<never, never>;
|
||||
/**
|
||||
* Placed at the end of each user page.
|
||||
* `user` is the user the page is displayed for.
|
||||
*/
|
||||
UserViewPage: {
|
||||
user: lib.UserDetails;
|
||||
};
|
||||
/** Placed at the end of the mods list page */
|
||||
ModsPage: Record<never, never>;
|
||||
/** Placed at the end of the roles list page. */
|
||||
RolesPage: Record<never, never>;
|
||||
/**
|
||||
* Placed at the end of each role page.
|
||||
* `role` is the role the page is displayed for.
|
||||
*/
|
||||
RoleViewPage: {
|
||||
role: lib.Role;
|
||||
search?: string;
|
||||
};
|
||||
};
|
||||
|
||||
export type PluginExtensionSlot = keyof ExtensionSlotProps;
|
||||
|
||||
export type PluginExtensionProps<K extends PluginExtensionSlot> = ExtensionSlotProps[K] & { component: K };
|
||||
|
||||
export type ExtensionComponent<K extends PluginExtensionSlot> = React.ComponentType<PluginExtensionProps<K>>;
|
||||
|
||||
export type ExtensionComponents = { [K in PluginExtensionSlot]: Map<string, ExtensionComponent<K>> };
|
||||
|
||||
export type WebPluginContext = lib.PluginLoadContext<{
|
||||
control: Control;
|
||||
container: any;
|
||||
package: any;
|
||||
/**
|
||||
* 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;
|
||||
/**
|
||||
* List of login forms provided by this plugin
|
||||
*/
|
||||
loginForms: PluginLoginForm[] = [];
|
||||
/**
|
||||
* List of pages provided by this plugin
|
||||
*/
|
||||
pages: PluginPage[] = [];
|
||||
/**
|
||||
* Additional Config inputComponent types available to render config
|
||||
* entries with.
|
||||
*/
|
||||
inputComponents: Record<string, InputComponent> = {};
|
||||
/**
|
||||
* Extra react component to add to core components
|
||||
*
|
||||
* Interface to augment core components of the web UI. Setting a
|
||||
* component as one of the supported properties of this object will
|
||||
* cause the web UI to render it when displaying that component,
|
||||
* usually at the end. Each component will receive a `plugin` param
|
||||
* which is the instance of the web plugin that contained the
|
||||
* component extra.
|
||||
*/
|
||||
componentExtra: {
|
||||
/** Placed at the end of the controller page. */
|
||||
ControllerPage?: React.ComponentType,
|
||||
/** Placed at the end of the hosts list page. */
|
||||
HostsPage?: React.ComponentType,
|
||||
/**
|
||||
* Placed at the end of each host page. Takes a `host` param which
|
||||
* is the host the page is displayed for.
|
||||
*/
|
||||
HostViewPage?: React.ComponentType,
|
||||
/** Placed at the end of the instance list page. */
|
||||
InstancesPage?: React.ComponentType,
|
||||
/**
|
||||
* Placed at the end of each instance page. Takes an `instance`
|
||||
* param which is the instance the page is displayed for.
|
||||
*/
|
||||
InstanceViewPage?: React.ComponentType,
|
||||
/** Placed at the end of the users list page. */
|
||||
UsersPage?: React.ComponentType,
|
||||
/**
|
||||
* Placed at the end of each user page. Takes a `user` param which
|
||||
* is the user object the page is displayed for.
|
||||
*/
|
||||
UserViewPage?: React.ComponentType,
|
||||
/** Placed at the end of the roles list page. */
|
||||
RolesPage?: React.ComponentType,
|
||||
/**
|
||||
* Placed at the end of each role page. Takes a `role` param which
|
||||
* is the role object the page is displayed for.
|
||||
*/
|
||||
RoleViewPage?: React.ComponentType,
|
||||
} = {};
|
||||
}, lib.PluginWebpackEnvInfo>;
|
||||
|
||||
|
||||
constructor(
|
||||
/**
|
||||
* Webpack container for this plugin
|
||||
*/
|
||||
public container: any,
|
||||
packageData: any,
|
||||
/**
|
||||
* The plugin's own info module
|
||||
*/
|
||||
public info: PluginWebpackEnvInfo,
|
||||
/**
|
||||
* Control link to the controller
|
||||
*
|
||||
* Not connected at the time init is invoked.
|
||||
*/
|
||||
public control: Control,
|
||||
logger: Logger,
|
||||
) {
|
||||
this.package = packageData;
|
||||
this.logger = logger.child({ plugin: this.info.name }) as unknown as Logger;
|
||||
/**
|
||||
* Collection of web plugin hooks
|
||||
*/
|
||||
export class WebHooks extends lib.AsyncHookCollection {
|
||||
constructor(logger: lib.Logger) {
|
||||
super(logger);
|
||||
this.controllerConnectionEvent = this.newHook();
|
||||
this.extensionComponents = this.newHook();
|
||||
this.inputComponents = this.newHook();
|
||||
this.loginForms = this.newHook();
|
||||
this.pages = this.newHook();
|
||||
}
|
||||
|
||||
/**
|
||||
* Called immediately after the class is instantiated.
|
||||
*/
|
||||
async init() { }
|
||||
|
||||
/**
|
||||
* Called when an event on the controller connection happens
|
||||
*
|
||||
@@ -212,5 +186,99 @@ export default class BaseWebPlugin {
|
||||
*
|
||||
* @param event - one of connect, drop, resume and close
|
||||
*/
|
||||
onControllerConnectionEvent(event: "connect" | "drop" | "resume" | "close") { }
|
||||
readonly controllerConnectionEvent: lib.AsyncHook<[event: "connect" | "drop" | "resume" | "close"]>;
|
||||
|
||||
/**
|
||||
* Collect additional UI components to render in core ui extension points.
|
||||
*
|
||||
* Each plugin may return a partial mapping of extension slot names
|
||||
* to React components. All returned components are rendered.
|
||||
*
|
||||
* Multiple plugins may contribute to the same slot.
|
||||
*/
|
||||
readonly extensionComponents: lib.AsyncHook<[], Partial<{
|
||||
[K in PluginExtensionSlot]: ExtensionComponent<K>;
|
||||
}>>;
|
||||
|
||||
/**
|
||||
* Collect additional config input components provided by plugins.
|
||||
*
|
||||
* Each plugin may return a mapping of input component names to React components.
|
||||
* These mappings are merged together to form the final registry.
|
||||
*
|
||||
* If multiple plugins define the same key, the last attached handler wins.
|
||||
*/
|
||||
readonly inputComponents: lib.AsyncHook<[], Record<string, InputComponent>>;
|
||||
|
||||
/**
|
||||
* Additional methods used to login to the web ui.
|
||||
*
|
||||
* All returned components are rendered.
|
||||
* Each must has a unique name prefixed with the plugin name.
|
||||
*/
|
||||
readonly loginForms: lib.AsyncHook<[], PluginLoginForm[]>;
|
||||
|
||||
/**
|
||||
* Additional pages accessible on the web ui.
|
||||
*
|
||||
* Each page must have a unique path.
|
||||
*/
|
||||
readonly pages: lib.AsyncHook<[], PluginPage[]>;
|
||||
}
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
|
||||
export interface BaseWebPlugin {
|
||||
onControllerConnectionEvent?(event: "connect" | "drop" | "resume" | "close"): void;
|
||||
}
|
||||
|
||||
/**
|
||||
* Base class for web interface plugins
|
||||
*/
|
||||
// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
|
||||
export class BaseWebPlugin {
|
||||
/**
|
||||
* Contents of the plugin's package.json file
|
||||
*/
|
||||
package: any;
|
||||
|
||||
pages: PluginPage[] = [];
|
||||
loginForms: PluginLoginForm[] = [];
|
||||
inputComponents: Record<string, InputComponent> = {};
|
||||
componentExtra: Partial<{
|
||||
[K in PluginExtensionSlot]: ExtensionComponent<K>;
|
||||
}> = {};
|
||||
|
||||
constructor(
|
||||
public container: any,
|
||||
packageData: any,
|
||||
public info: lib.PluginWebpackEnvInfo,
|
||||
public control: Control,
|
||||
public logger: lib.Logger,
|
||||
) {
|
||||
this.package = packageData; // strict mode complains if we don't assign it this way
|
||||
|
||||
if (this.onControllerConnectionEvent) {
|
||||
control.hooks.controllerConnectionEvent.attach(info.name, this.onControllerConnectionEvent.bind(this));
|
||||
}
|
||||
|
||||
// Subclasses populate these fields in init(), which runs after the
|
||||
// constructor, so the handlers read them when the hook is collected.
|
||||
control.hooks.inputComponents.attach(info.name, () => this.inputComponents);
|
||||
control.hooks.extensionComponents.attach(info.name, () => this.componentExtra);
|
||||
control.hooks.loginForms.attach(info.name, () => this.loginForms);
|
||||
control.hooks.pages.attach(info.name, () => this.pages);
|
||||
}
|
||||
|
||||
static fromContext(context: WebPluginContext): BaseWebPlugin {
|
||||
return new this(context.container, context.package, context.plugin, context.control, context.logger);
|
||||
}
|
||||
|
||||
detachHooks() {
|
||||
this.control.hooks.detachAll(this.info.name);
|
||||
}
|
||||
|
||||
/**
|
||||
* Called immediately after the class is instantiated.
|
||||
*/
|
||||
async init() {}
|
||||
}
|
||||
Reference in new issue
Block a user