feat: first stab at documenting plugins + simplified plugin architecture

Author: calebjclark

client/lib/Agent.ts

@@ -27,7 +27,7 @@ import CSSStyleDeclaration from 'awaited-dom/impl/official-klasses/CSSStyleDecla
 import IAgentMeta from '@secret-agent/interfaces/IAgentMeta';
 import IScreenshotOptions from '@secret-agent/interfaces/IScreenshotOptions';
 import { INodeVisibility } from '@secret-agent/interfaces/INodeVisibility';
-import { IClientExtender } from '@secret-agent/interfaces/IPluginClientExtender';
+import { IClientPlugin } from '@secret-agent/interfaces/IClientPlugin';
 import IAgent from '@secret-agent/interfaces/IAgent';
 import WebsocketResource from './WebsocketResource';
 import IWaitForResourceFilter from '../interfaces/IWaitForResourceFilter';
@@ -52,7 +52,7 @@ import FrameEnvironment, {
   getCoreFrameEnvironment,
   getCoreFrameEnvironmentForPosition,
 } from './FrameEnvironment';
-import getClientExtenderPluginClass from './getClientExtenderPluginClass';
+import getClientPluginClass from './getClientPluginClass';
 import FrozenTab from './FrozenTab';
 import FileChooser from './FileChooser';
 import Output, { createObservableOutput } from './Output';
@@ -70,7 +70,7 @@ export interface IState {
   connection: SessionConnection;
   isClosing: boolean;
   options: ISessionCreateOptions & Pick<IAgentCreateOptions, 'connectionToCore' | 'showReplay'>;
-  plugins: IClientExtender[];
+  clientPlugins: IClientPlugin[];
 }
 
 const propertyKeys: (keyof Agent)[] = [
@@ -122,7 +122,7 @@ export default class Agent extends AwaitedEventTarget<{ close: void }> implement
         scriptInstanceMeta: scriptInstance.meta,
         dependencyMap: {},
       },
-      plugins: [],
+      clientPlugins: [],
     });
   }
 
@@ -317,11 +317,11 @@ export default class Agent extends AwaitedEventTarget<{ close: void }> implement
   // PLUGINS
 
   public use(PluginObject): Agent {
-    const ClientExtender = getClientExtenderPluginClass(PluginObject);
-    const { plugins, options } = getState(this);
-    const plugin = new ClientExtender();
-    plugins.push(plugin);
-    options.dependencyMap[ClientExtender.id] = ClientExtender.coreDependencyIds || [];
+    const ClientPlugin = getClientPluginClass(PluginObject);
+    const { clientPlugins, options } = getState(this);
+    const clientPlugin = new ClientPlugin();
+    clientPlugins.push(clientPlugin);
+    options.dependencyMap[ClientPlugin.id] = ClientPlugin.coreDependencyIds || [];
     return this;
   }
 
@@ -507,7 +507,7 @@ class SessionConnection {
     }
     this.hasConnected = true;
 
-    const { plugins } = getState(this.agent);
+    const { clientPlugins } = getState(this.agent);
     const { showReplay, connectionToCore, ...options } = getState(this.agent)
       .options as IAgentCreateOptions;
 
@@ -536,16 +536,16 @@ class SessionConnection {
     this._activeTab = createTab(this.agent, coreTab);
     this._tabs = [this._activeTab];
 
-    for (const plugin of plugins) {
-      await plugin.onAgent(this.agent, this.sendToActiveTab.bind(this));
+    for (const clientPlugin of clientPlugins) {
+      await clientPlugin.onAgent(this.agent, this.sendToActiveTab.bind(this));
     }
 
     return await coreSession;
   }
 
-  private async sendToActiveTab(sendToPluginId: string, ...args: any[]): Promise<any> {
+  private async sendToActiveTab(toPluginId: string, ...args: any[]): Promise<any> {
     const coreSession = (await this._coreSession) as CoreSession;
     const coreTab = coreSession.tabsById.get(await this._activeTab.tabId);
-    return coreTab.commandQueue.run('Tab.runPluginCommand', sendToPluginId, args);
+    return coreTab.commandQueue.run('Tab.runPluginCommand', toPluginId, args);
   }
 }

client/lib/Tab.ts

@@ -89,8 +89,8 @@ export default class Tab extends AwaitedEventTarget<IEventType> implements ITab
       return (await coreTab).commandQueue.run('Tab.runPluginCommand', pluginId, args);
     }
 
-    for (const plugin of agentState.getState(agent).plugins) {
-      plugin.onTab(agent, this, sendToTab);
+    for (const clientPlugin of agentState.getState(agent).clientPlugins) {
+      clientPlugin.onTab(agent, this, sendToTab);
     }
   }
 

client/lib/getClientExtenderPluginClass.ts

@@ -0,0 +1,21 @@
+import { IClientPluginClass } from '@secret-agent/interfaces/IClientPlugin';
+import ClientPlugin from '@secret-agent/plugin-utils/lib/ClientPlugin';
+import { PluginTypes } from '@secret-agent/interfaces/IPluginTypes';
+
+export default function getClientPluginClass(PluginObject: any): IClientPluginClass {
+  if (isClientPluginClass(PluginObject)) {
+    return PluginObject;
+  }
+  if (isClientPluginClass(PluginObject.ClientPlugin)) {
+    return PluginObject.ClientPlugin;
+  }
+  throw new Error(`Plugin (${PluginObject.name}) is not a valid ClientPlugin`);
+}
+
+function isClientPluginClass(PluginObject: any): boolean {
+  if (!PluginObject) return false;
+  if (PluginObject.prototype instanceof ClientPlugin) {
+    return true;
+  }
+  return PluginObject.type === PluginTypes.ClientPlugin;
+}

client/lib/getClientPluginClass.ts

@@ -2,9 +2,11 @@ import ICoreConfigureOptions from '@secret-agent/interfaces/ICoreConfigureOption
 import { LocationTrigger } from '@secret-agent/interfaces/Location';
 import Log, { hasBeenLoggedSymbol } from '@secret-agent/commons/Logger';
 import Resolvable from '@secret-agent/commons/Resolvable';
-import { IHumanEmulatorClass } from '@secret-agent/interfaces/IPluginHumanEmulator';
-import { IBrowserEmulatorClass } from '@secret-agent/interfaces/IPluginBrowserEmulator';
-import { ICoreExtenderClass } from '@secret-agent/interfaces/IPluginCoreExtender';
+import {
+  IHumanEmulatorClass,
+  IBrowserEmulatorClass,
+  ICorePluginClass,
+} from '@secret-agent/interfaces/ICorePlugin';
 import { PluginTypes } from '@secret-agent/interfaces/IPluginTypes';
 import DefaultBrowserEmulator from '@secret-agent/default-browser-emulator';
 import DefaultHumanEmulator from '@secret-agent/default-human-emulator';
@@ -24,17 +26,17 @@ export default class Core {
   public static server = new CoreServer();
   public static readonly connections: ConnectionToClient[] = [];
   public static pluginMap: {
-    humanEmulatorsById: { [id: string]: IHumanEmulatorClass }
-    browserEmulatorsById: { [id: string]: IBrowserEmulatorClass }
-    coreExtenders: ICoreExtenderClass[];
+    humanEmulatorsById: { [id: string]: IHumanEmulatorClass };
+    browserEmulatorsById: { [id: string]: IBrowserEmulatorClass };
+    corePlugins: ICorePluginClass[];
   } = {
     humanEmulatorsById: {
       [DefaultHumanEmulator.id]: DefaultHumanEmulator,
     },
     browserEmulatorsById: {
       [DefaultBrowserEmulator.id]: DefaultBrowserEmulator,
     },
-    coreExtenders: [],
+    corePlugins: [],
   };
 
   public static onShutdown: () => void;
@@ -55,13 +57,13 @@ export default class Core {
     return connection;
   }
 
-  public static use(Plugin: IHumanEmulatorClass | IBrowserEmulatorClass | ICoreExtenderClass) {
-    if (Plugin.pluginType === PluginTypes.HumanEmulator) {
-      this.pluginMap.humanEmulatorsById[Plugin.id] = Plugin;
-    } else if (Plugin.pluginType === PluginTypes.BrowserEmulator) {
-      this.pluginMap.browserEmulatorsById[Plugin.id] = Plugin;
-    } else if (Plugin.pluginType === PluginTypes.CoreExtender) {
-      this.pluginMap.coreExtenders.push(Plugin);
+  public static use(CorePlugin: ICorePluginClass) {
+    if (CorePlugin.type === PluginTypes.HumanEmulator) {
+      this.pluginMap.humanEmulatorsById[CorePlugin.id] = CorePlugin as IHumanEmulatorClass;
+    } else if (CorePlugin.type === PluginTypes.BrowserEmulator) {
+      this.pluginMap.browserEmulatorsById[CorePlugin.id] = CorePlugin as IBrowserEmulatorClass;
+    } else if (CorePlugin.type === PluginTypes.CorePlugin) {
+      this.pluginMap.corePlugins.push(CorePlugin);
     } else {
       throw new Error('Unknown plugin type');
     }

core/index.ts

@@ -1,6 +1,5 @@
 import { URL } from 'url';
 import { IBoundLog } from '@secret-agent/interfaces/ILog';
-import { ICoreExtender, IOnCommandMeta } from '@secret-agent/interfaces/IPluginCoreExtender';
 import { IPuppetPage } from '@secret-agent/interfaces/IPuppetPage';
 import { IPuppetWorker } from '@secret-agent/interfaces/IPuppetWorker';
 import IHttpResourceLoadDetails from '@secret-agent/interfaces/IHttpResourceLoadDetails';
@@ -10,15 +9,16 @@ import ITlsSettings from '@secret-agent/interfaces/ITlsSettings';
 import { IInteractionGroups, IInteractionStep } from '@secret-agent/interfaces/IInteractions';
 import IInteractionsHelper from '@secret-agent/interfaces/IInteractionsHelper';
 import IPoint from '@secret-agent/interfaces/IPoint';
-import {
+import ICorePlugin, {
+  IHumanEmulator,
   IBrowserEmulator,
   IBrowserEmulatorConfig,
   ISelectBrowserMeta,
-} from '@secret-agent/interfaces/IPluginBrowserEmulator';
-import { IHumanEmulator } from '@secret-agent/interfaces/IPluginHumanEmulator';
-import IPlugins from '@secret-agent/interfaces/IPlugins';
-import IPlugin, { IPluginClass } from '@secret-agent/interfaces/IPlugin';
-import IPluginCreateOptions from '@secret-agent/interfaces/IPluginCreateOptions';
+  ICorePluginClass,
+  IOnClientCommandMeta,
+} from '@secret-agent/interfaces/ICorePlugin';
+import ICorePlugins from '@secret-agent/interfaces/ICorePlugins';
+import ICorePluginCreateOptions from '@secret-agent/interfaces/ICorePluginCreateOptions';
 import IBrowserEngine from '@secret-agent/interfaces/IBrowserEngine';
 import { PluginTypes } from '@secret-agent/interfaces/IPluginTypes';
 import Core from '../index';
@@ -34,16 +34,16 @@ interface IOptionsCreate {
   dependencyMap?: { [clientPluginId: string]: string[] };
 }
 
-export default class Plugins implements IPlugins {
-  public static pluginClassesById: { [id: string]: IPluginClass } = {};
+export default class CorePlugins implements ICorePlugins {
+  public static corePluginClassesById: { [id: string]: ICorePluginClass } = {};
 
   public readonly browserEngine: IBrowserEngine;
   public readonly browserEmulator: IBrowserEmulator;
   public readonly humanEmulator: IHumanEmulator;
 
-  private readonly instances: ICoreExtender[] = [];
-  private readonly instanceById: { [id: string]: ICoreExtender } = {};
-  private readonly createOptions: IPluginCreateOptions;
+  private readonly instances: ICorePlugin[] = [];
+  private readonly instanceById: { [id: string]: ICorePlugin } = {};
+  private readonly createOptions: ICorePluginCreateOptions;
   private readonly logger: IBoundLog;
 
   constructor(options: IOptionsCreate, logger: IBoundLog) {
@@ -66,34 +66,34 @@ export default class Plugins implements IPlugins {
 
     const { browserEngine, userAgentOption } =
       options.selectBrowserMeta || BrowserEmulator.selectBrowserMeta(userAgentSelector);
-    this.createOptions = { browserEngine, logger, plugins: this };
+    this.createOptions = { browserEngine, userAgentOption, logger, corePlugins: this };
     this.browserEngine = browserEngine;
     this.logger = logger;
 
-    this.browserEmulator = new BrowserEmulator(this.createOptions, userAgentOption);
+    this.browserEmulator = new BrowserEmulator(this.createOptions);
     this.addPluginInstance(this.browserEmulator);
 
     this.humanEmulator = new HumanEmulator(this.createOptions);
     this.addPluginInstance(this.humanEmulator);
 
-    Core.pluginMap.coreExtenders.forEach(x => this.use(x));
+    Core.pluginMap.corePlugins.forEach(x => this.use(x));
 
     if (dependencyMap && Core.allowDynamicPluginDependencies) {
       Object.entries(dependencyMap).forEach(([clientPluginId, dependentPluginIds]) => {
-        dependentPluginIds.forEach(pluginId => {
-          if (this.instanceById[pluginId]) return;
-          this.logger.info(`Dynamically using ${pluginId} required by ${clientPluginId}`);
-          const Plugin = this.require(pluginId);
-          if (!Plugin) {
-            this.logger.warn(`Could not find ${pluginId} required by ${clientPluginId}`);
+        dependentPluginIds.forEach(corePluginId => {
+          if (this.instanceById[corePluginId]) return;
+          this.logger.info(`Dynamically using ${corePluginId} required by ${clientPluginId}`);
+          const PluginObject = this.require(corePluginId);
+          if (!PluginObject) {
+            this.logger.warn(`Could not find ${corePluginId} required by ${clientPluginId}`);
             return;
           }
-          const CoreExtender = (Plugin as any).CoreExtender || Plugin;
-          if (CoreExtender.pluginType !== PluginTypes.CoreExtender) {
-            this.logger.warn(`Could not use ${pluginId} because it's not a CoreExtender`);
+          const CorePlugin = (PluginObject as any).CorePlugin || PluginObject;
+          if (CorePlugin.type !== PluginTypes.CorePlugin) {
+            this.logger.warn(`Could not use ${corePluginId} because it's not a CorePlugin`);
             return;
           }
-          this.use(CoreExtender);
+          this.use(CorePlugin);
         });
       });
     }
@@ -176,40 +176,40 @@ export default class Plugins implements IPlugins {
   // PLUGIN COMMANDS
 
   public async onPluginCommand(
-    sendToPluginId: string,
-    commandMeta: IOnCommandMeta,
+    toPluginId: string,
+    commandMeta: IOnClientCommandMeta,
     args: any[],
   ): Promise<any> {
-    const plugin = this.instanceById[sendToPluginId];
-    if (plugin && plugin.onCommand) {
-      return await plugin.onCommand(commandMeta, ...args);
+    const plugin = this.instanceById[toPluginId];
+    if (plugin && plugin.onClientCommand) {
+      return await plugin.onClientCommand(commandMeta, ...args);
     }
-    this.logger.warn(`Plugin (${sendToPluginId}) could not be found for command`);
+    this.logger.warn(`Plugin (${toPluginId}) could not be found for command`);
   }
 
   // ADDING PLUGINS TO THE STACK
 
-  public use(Plugin: IPluginClass) {
-    if (this.instanceById[Plugin.id]) return;
-    this.addPluginInstance(new Plugin(this.createOptions));
+  public use(CorePlugin: ICorePluginClass) {
+    if (this.instanceById[CorePlugin.id]) return;
+    this.addPluginInstance(new CorePlugin(this.createOptions));
   }
 
-  private addPluginInstance(plugin: IPlugin) {
-    this.instances.push(plugin);
-    this.instanceById[plugin.id] = plugin;
+  private addPluginInstance(corePlugin: ICorePlugin) {
+    this.instances.push(corePlugin);
+    this.instanceById[corePlugin.id] = corePlugin;
   }
 
-  private require(pluginId: string): IPluginClass {
-    if (!Plugins.pluginClassesById[pluginId]) {
+  private require(corePluginId: string): ICorePluginClass {
+    if (!CorePlugins.corePluginClassesById[corePluginId]) {
       try {
         // eslint-disable-next-line global-require,import/no-dynamic-require
-        const Plugin = require(pluginId);
-        if (!Plugin) return;
-        Plugins.pluginClassesById[pluginId] = Plugin.default || Plugin;
+        const CorePlugin = require(corePluginId);
+        if (!CorePlugin) return;
+        CorePlugins.corePluginClassesById[corePluginId] = CorePlugin.default || CorePlugin;
       } catch (error) {
         return;
       }
     }
-    return Plugins.pluginClassesById[pluginId];
+    return CorePlugins.corePluginClassesById[corePluginId];
   }
 }

core/lib/Plugins.ts core/lib/CorePlugins.tscore/lib/Plugins.ts renamed to core/lib/CorePlugins.ts

@@ -23,7 +23,7 @@ import IPoint from '@secret-agent/interfaces/IPoint';
 import IMouseUpResult from '@secret-agent/interfaces/IMouseUpResult';
 import IResolvablePromise from '@secret-agent/interfaces/IResolvablePromise';
 import { IPuppetKeyboard, IPuppetMouse } from '@secret-agent/interfaces/IPuppetInput';
-import IPlugins from '@secret-agent/interfaces/IPlugins';
+import ICorePlugins from '@secret-agent/interfaces/ICorePlugins';
 import IViewport from '@secret-agent/interfaces/IViewport';
 import IElementRect from '@secret-agent/interfaces/IElementRect';
 import { INodeVisibility } from '@secret-agent/interfaces/INodeVisibility';
@@ -83,7 +83,7 @@ export default class Interactor implements IInteractionsHelper {
     return this.tab.puppetPage.keyboard;
   }
 
-  private get plugins(): IPlugins {
+  private get plugins(): ICorePlugins {
     return this.tab.session.plugins;
   }