@flowscripter/dynamic-plugin-framework 1.2.0

package/src/plugin_manager/plugin_repository/PluginRepository.ts

@@ -0,0 +1,30 @@
+import type ExtensionEntry from "./ExtensionEntry.ts";
+import type ExtensionDescriptor from "../../api/plugin/ExtensionDescriptor.ts";
+
+/**
+ * A source of {@link Plugin} implementations.
+ */
+export default interface PluginRepository {
+  /**
+   * Return an {@link ExtensionEntry} for each Extension hosted in the Plugin Repository which provides an
+   * Extension for the specified Extension Point.
+   *
+   * @param extensionPoint the Extension Point for which to return {@link ExtensionEntry} instances.
+   *
+   * @return an async iterable of {@link ExtensionEntry} instances for all matching Extensions.
+   */
+  scanForExtensions(
+    extensionPoint: string,
+  ): AsyncIterable<Readonly<ExtensionEntry>>;
+
+  /**
+   * Return the {@link ExtensionDescriptor} for the Extension identified by the specified {@link ExtensionEntry}.
+   *
+   * @param extensionEntry the {@link extensionEntry} for the desired Extension.
+   *
+   * @return an {@link ExtensionDescriptor} instance.
+   */
+  getExtensionDescriptorFromExtensionEntry(
+    extensionEntry: ExtensionEntry,
+  ): Promise<Readonly<ExtensionDescriptor>>;
+}

package/src/plugin_manager/plugin_repository/UrlListPluginRepository.ts

@@ -0,0 +1,105 @@
+import type PluginRepository from "./PluginRepository.ts";
+import type ExtensionDescriptor from "../../api/plugin/ExtensionDescriptor.ts";
+import type ExtensionEntry from "./ExtensionEntry.ts";
+import UrlPluginSource from "./UrlPluginSource.ts";
+
+/**
+ * Implementation of {@link PluginRepository} using a provided set of URLs to access Plugins.
+ *
+ * When scanning for Plugins each provided URL will be used to attempt to load a Plugin and examine it.
+ */
+export default class UrlListPluginRepository implements PluginRepository {
+  private readonly urls: Set<string>;
+  private readonly pluginSource = new UrlPluginSource();
+
+  /**
+   * Constructor configures the instance using the specified set of URLs.
+   *
+   * @throws *Error* if the URL set contains a non-valid URL.
+   */
+  public constructor(urls: Set<string>) {
+    if (!urls || (urls.size === 0)) {
+      throw new Error(`Undefined or empty set of URLs provided`);
+    }
+    this.urls = urls;
+    this.urls.forEach((url) => {
+      try {
+        new URL(url);
+      } catch (err) {
+        throw new Error(
+          `Cannot parse ${url} as a URL: ${(err as Error).message}`,
+        );
+      }
+    });
+  }
+
+  private async *getExtensionEntryAsyncIterable(
+    extensionPoint: string,
+  ): AsyncIterable<ExtensionEntry> {
+    // As this is just a list of URLs we need to load each and then filter for extensionPoint
+    for await (const candidateUrl of this.urls) {
+      const plugin = await this.pluginSource.loadPlugin(new URL(candidateUrl));
+
+      if (plugin) {
+        // filter Extensions in each Plugin by specified Extension Point
+        // and map any matches to an Extension Entry
+        for (let i = 0; i < plugin.extensionDescriptors.length; i++) {
+          const extensionDescripter = plugin.extensionDescriptors[i];
+          if (extensionDescripter.extensionPoint !== extensionPoint) {
+            continue;
+          }
+          yield {
+            pluginId: candidateUrl,
+            extensionId: `${i}`,
+            extensionPoint,
+            pluginData: plugin.pluginData,
+            extensionData: extensionDescripter.extensionData,
+          };
+        }
+      }
+    }
+  }
+
+  public scanForExtensions(
+    extensionPoint: string,
+  ): AsyncIterable<ExtensionEntry> {
+    return this.getExtensionEntryAsyncIterable(extensionPoint);
+  }
+
+  /**
+   * @inheritDoc
+   *
+   * @throws *Error* if the specified ExtensionEntry is unknown.
+   */
+  public async getExtensionDescriptorFromExtensionEntry(
+    extensionEntry: ExtensionEntry,
+  ): Promise<Readonly<ExtensionDescriptor>> {
+    const plugin = await this.pluginSource.loadPlugin(
+      new URL(extensionEntry.pluginId),
+    );
+
+    if (!plugin) {
+      return Promise.reject(`Plugin ID ${extensionEntry.pluginId} is unknown`);
+    }
+
+    let extensionId = -1;
+
+    try {
+      extensionId = parseInt(extensionEntry.extensionId);
+    } catch (_e) {
+      return Promise.reject(
+        `Extension ID ${extensionEntry.extensionId} is unknown`,
+      );
+    }
+
+    if (
+      (extensionId < 0) || (extensionId >= plugin.extensionDescriptors.length)
+    ) {
+      return Promise.reject(
+        `Extension ID ${extensionEntry.extensionId} is unknown`,
+      );
+    }
+
+    return Promise.resolve(plugin.extensionDescriptors[extensionId]);
+  }
+}

package/src/plugin_manager/plugin_repository/UrlPluginSource.ts

@@ -0,0 +1,34 @@
+import type Plugin from "../../api/plugin/Plugin.ts";
+import loadPlugin from "../util/PluginLoader.ts";
+
+/**
+ * A source of {@link Plugin} instances sourced from URLs.
+ *
+ * Any loaded URLs will be cached so that subsequent calls to {@link loadPlugin} are (possibly) lower cost.
+ */
+export default class UrlPluginSource {
+  private readonly pluginsByUrl: Map<URL, Plugin> = new Map();
+
+  /**
+   * Attempt to load a {@link Plugin} object from the specified URL.
+   *
+   * @param url the URL to load from
+   *
+   * @returns a {@link Plugin} object if successful otherwise undefined
+   */
+  public async loadPlugin(url: URL): Promise<Plugin | undefined> {
+    let plugin = this.pluginsByUrl.get(url);
+
+    if (!plugin) {
+      const pluginLoadResult = await loadPlugin(url.toString());
+      if (
+        pluginLoadResult.isValidPlugin &&
+        (pluginLoadResult.plugin !== undefined)
+      ) {
+        plugin = pluginLoadResult.plugin;
+        this.pluginsByUrl.set(url, plugin);
+      }
+    }
+    return Promise.resolve(this.pluginsByUrl.get(url));
+  }
+}

package/src/plugin_manager/registry/ExtensionPointRegistry.ts

@@ -0,0 +1,25 @@
+/**
+ * A registry of Extension Points.
+ */
+export default interface ExtensionPointRegistry {
+  /**
+   * Register a specified Extension Point.
+   *
+   * @param extensionPoint the Extension Point to register
+   */
+  register(extensionPoint: string): Promise<void>;
+
+  /**
+   * Return all registered Extension Points.
+   *
+   * @return Set of Extension Points
+   */
+  getAll(): Promise<ReadonlySet<string>>;
+
+  /**
+   * Returns *true* if the specified Extension Point has been registered.
+   *
+   * @param extensionPoint the Extension Point to check
+   */
+  isRegistered(extensionPoint: string): Promise<boolean>;
+}

package/src/plugin_manager/registry/ExtensionRegistry.ts

@@ -0,0 +1,38 @@
+import type ExtensionEntry from "../plugin_repository/ExtensionEntry.ts";
+
+/**
+ * A registry of Extensions.
+ */
+export default interface ExtensionRegistry {
+  /**
+   * Register a specified {@link ExtensionEntry} with a specified Extension handle.
+   *
+   * @param extensionHandle a unique identifier under which to register the {@link ExtensionEntry}
+   * @param extensionEntry the {@link ExtensionEntry} for the Extension to register
+   */
+  register(
+    extensionHandle: string,
+    extensionEntry: ExtensionEntry,
+  ): Promise<void>;
+
+  /**
+   * Return the specified registered {@link ExtensionEntry} instance.
+   *
+   * @param extensionHandle the handle for the desired {@link ExtensionEntry} instance
+   *
+   * @return an {@link ExtensionEntry} instance
+   */
+  get(extensionHandle: string): Promise<Readonly<ExtensionEntry>>;
+
+  /**
+   * Return {@link ExtensionEntry} instances for registered Extensions implementing the specified Extension Point.
+   *
+   * @param extensionPoint the Extension Point to match
+   *
+   * @return a map of extension handle to {@link ExtensionEntry} for all matching
+   * registered {@link ExtensionEntry} instances
+   */
+  getExtensions(
+    extensionPoint: string,
+  ): Promise<ReadonlyMap<string, ExtensionEntry>>;
+}

package/src/plugin_manager/registry/InMemoryExtensionPointRegistry.ts

@@ -0,0 +1,29 @@
+import type ExtensionPointRegistry from "./ExtensionPointRegistry.ts";
+
+/**
+ * Simple implementation of an {@link ExtensionPointRegistry} using an in-memory Set.
+ */
+export default class InMemoryExtensionPointRegistry
+  implements ExtensionPointRegistry {
+  private readonly extensionPoints: Set<string> = new Set();
+
+  /**
+   * @inheritDoc
+   *
+   * @throws *Error* if the specified Extension Point has already been registered
+   */
+  public async register(extensionPoint: string): Promise<void> {
+    if (await this.isRegistered(extensionPoint)) {
+      throw new Error(`Extension Point ${extensionPoint} already registered`);
+    }
+    this.extensionPoints.add(extensionPoint);
+  }
+
+  public getAll(): Promise<ReadonlySet<string>> {
+    return Promise.resolve(this.extensionPoints);
+  }
+
+  public isRegistered(extensionPoint: string): Promise<boolean> {
+    return Promise.resolve(this.extensionPoints.has(extensionPoint));
+  }
+}

package/src/plugin_manager/registry/InMemoryExtensionRegistry.ts

@@ -0,0 +1,69 @@
+import type ExtensionRegistry from "./ExtensionRegistry.ts";
+import type ExtensionEntry from "../plugin_repository/ExtensionEntry.ts";
+
+/**
+ * Simple implementation of an {@link ExtensionRegistry} using an in-memory map.
+ */
+export default class InMemoryExtensionRegistry implements ExtensionRegistry {
+  private readonly extensionEntriesByHandle: Map<string, ExtensionEntry> =
+    new Map();
+
+  private readonly extensionEntriesByExtensionPoint: Map<
+    string,
+    Map<string, ExtensionEntry>
+  > = new Map();
+
+  /**
+   * @inheritDoc
+   *
+   * @throws *Error* if the specified Extension handle has already been registered
+   */
+  public register(
+    extensionHandle: string,
+    extensionEntry: ExtensionEntry,
+  ): Promise<void> {
+    if (this.extensionEntriesByHandle.has(extensionHandle)) {
+      return Promise.reject(
+        `Extension handle ${extensionHandle} has already been registered`,
+      );
+    }
+    this.extensionEntriesByHandle.set(extensionHandle, extensionEntry);
+
+    let extensionEntries = this.extensionEntriesByExtensionPoint.get(
+      extensionEntry.extensionPoint,
+    );
+
+    if (extensionEntries === undefined) {
+      extensionEntries = new Map();
+      this.extensionEntriesByExtensionPoint.set(
+        extensionEntry.extensionPoint,
+        extensionEntries,
+      );
+    }
+    extensionEntries.set(extensionHandle, extensionEntry);
+
+    return Promise.resolve();
+  }
+
+  /**
+   * @inheritDoc
+   *
+   * @throws *Error* if the specified Extension handle has not been registered
+   */
+  public get(extensionHandle: string): Promise<Readonly<ExtensionEntry>> {
+    const extensionEntry = this.extensionEntriesByHandle.get(extensionHandle);
+
+    if (!extensionEntry) {
+      return Promise.reject(`Extension handle ${extensionHandle} is unknown`);
+    }
+    return Promise.resolve(Object.freeze(extensionEntry));
+  }
+
+  public getExtensions(
+    extensionPoint: string,
+  ): Promise<ReadonlyMap<string, ExtensionEntry>> {
+    return Promise.resolve(
+      this.extensionEntriesByExtensionPoint.get(extensionPoint) || new Map(),
+    );
+  }
+}

package/src/plugin_manager/util/PluginLoader.ts

@@ -0,0 +1,93 @@
+import type Plugin from "../../api/plugin/Plugin.ts";
+
+/**
+ * Result of a {@link loadPlugin} invocation.
+ */
+export interface PluginLoadResult {
+  /**
+   * `true` if the module at the specified URL is a valid {@link Plugin} implementation.
+   */
+  isValidPlugin: boolean;
+
+  /**
+   * Populated with the {@link Plugin} object if {@link PluginLoadResult.isValidPlugin} is `true`
+   */
+  plugin: Plugin | undefined;
+
+  /**
+   * Populated if {@link PluginLoadResult.isValidPlugin} is `false`
+   */
+  error?: Error;
+}
+
+/**
+ * Utility function to import a specified module and validate it is a {@link Plugin} implementation.
+ *
+ * @param url the URL of the module to import
+ */
+export default async function loadPlugin(
+  url: string,
+): Promise<Readonly<PluginLoadResult>> {
+  const result: PluginLoadResult = {
+    isValidPlugin: false,
+    plugin: undefined,
+    error: undefined,
+  };
+
+  let module;
+
+  try {
+    module = await import(url);
+  } catch (err) {
+    result.error = err as Error;
+    return result;
+  }
+
+  const potentialPlugin = module.default;
+
+  // check the assumed Plugin has an array of extension descriptors
+  if (!Array.isArray(potentialPlugin.extensionDescriptors)) {
+    result.error = new Error(
+      `Plugin from ${url} does not provide an extensionDescriptors array`,
+    );
+    return result;
+  }
+
+  // At this point assume it is a valid plugin and then disprove this
+  result.isValidPlugin = true;
+
+  for (
+    const potentialExtensionDescriptor of potentialPlugin
+      .extensionDescriptors
+  ) {
+    // check for valid {@link ExtensionDescriptor.extensionPoint}
+    if (
+      (potentialExtensionDescriptor.extensionPoint === undefined) ||
+      (!(potentialExtensionDescriptor.extensionPoint as unknown instanceof
+        String) &&
+        (typeof potentialExtensionDescriptor.extensionPoint !== "string"))
+    ) {
+      result.isValidPlugin = false;
+      result.error = new Error(
+        `Plugin from ${url} does not provide an extensionPoint string in one of the extensionDescriptors`,
+      );
+      return result;
+    }
+    // check for valid {@link ExtensionDescriptor.factory.create function}
+    if (
+      (potentialExtensionDescriptor.factory === undefined) ||
+      (potentialExtensionDescriptor.factory.create === undefined) ||
+      !(potentialExtensionDescriptor.factory.create as unknown instanceof
+        Function)
+    ) {
+      result.isValidPlugin = false;
+      result.error = new Error(
+        `Plugin from ${url} does not provide a factory with a create function in one of the extensionDescriptors`,
+      );
+      return result;
+    }
+  }
+
+  result.plugin = potentialPlugin;
+  return result;
+}

package/tests/fixtures/Constants.ts

@@ -0,0 +1,15 @@
+export const EXTENSION_POINT_1 = "foo";
+export const EXTENSION_POINT_2 = "bar";
+
+export const PLUGIN_1_ID = "Plugin1";
+export const PLUGIN_2_ID = "Plugin2";
+
+export const EXTENSION_1_ID = "1";
+export const EXTENSION_2_ID = "2";
+
+export const EXTENSION_1_HANDLE = "foobar1";
+export const EXTENSION_2_HANDLE = "foobar2";
+
+export interface ExtensionPoint1 {
+  sayHello(): string;
+}

package/tests/fixtures/InvalidPlugin1.ts

@@ -0,0 +1 @@
+export default {};

package/tests/fixtures/InvalidPlugin2.ts

@@ -0,0 +1,5 @@
+export default {
+  extensionDescriptors: [{
+    extensionData: "foo",
+  }],
+};

package/tests/fixtures/InvalidPlugin3.ts

@@ -0,0 +1,5 @@
+export default {
+  extensionDescriptors: [{
+    extensionPoint: "foo",
+  }],
+};

package/tests/fixtures/InvalidPlugin4.ts

@@ -0,0 +1,6 @@
+export default {
+  extensionDescriptors: [{
+    extensionPoint: "foo",
+    factory: "bar",
+  }],
+};

package/tests/fixtures/InvalidPlugin5.ts

@@ -0,0 +1,8 @@
+export default {
+  extensionDescriptors: [{
+    extensionPoint: "foo",
+    factory: {
+      bar: () => {},
+    },
+  }],
+};

package/tests/fixtures/ValidPlugin1.ts

@@ -0,0 +1,34 @@
+import type Plugin from "../../src/api/plugin/Plugin.ts";
+import type ExtensionDescriptor from "../../src/api/plugin/ExtensionDescriptor.ts";
+import type ExtensionFactory from "../../src/api/plugin/ExtensionFactory.ts";
+import { EXTENSION_POINT_1, type ExtensionPoint1 } from "./Constants.ts";
+
+const extension1: ExtensionPoint1 = {
+  sayHello: () => {
+    return "hello";
+  },
+};
+
+const extensionFactory1: ExtensionFactory = {
+  create: () => {
+    return Promise.resolve(extension1);
+  },
+};
+
+export const extensionDescriptor1: ExtensionDescriptor = {
+  extensionPoint: EXTENSION_POINT_1,
+
+  factory: extensionFactory1,
+
+  extensionData: new Map([["foo", "bar"]]),
+};
+
+const plugin1: Plugin = {
+  pluginData: new Map([["foo", "bar"]]),
+
+  extensionDescriptors: [
+    extensionDescriptor1,
+  ],
+};
+
+export default plugin1;

package/tests/plugin_manager/DefaultPluginManager_test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import DefaultPluginManager from "../../src/plugin_manager/DefaultPluginManager.ts";
+import UrlListPluginRepository from "../../src/plugin_manager/plugin_repository/UrlListPluginRepository.ts";
+import {
+  EXTENSION_POINT_1,
+  type ExtensionPoint1,
+} from "../fixtures/Constants.ts";
+
+const PLUGIN_1_URL = "file://" +
+  path.join(
+    path.dirname(Bun.fileURLToPath(import.meta.url)),
+    "../fixtures/ValidPlugin1.ts",
+  );
+
+describe("DefaultPluginManager Tests", () => {
+  test("Register without a plugin repository does not fail", async () => {
+    const defaultPluginManager = new DefaultPluginManager([]);
+
+    await defaultPluginManager.registerExtensions(EXTENSION_POINT_1);
+  });
+
+  test("Successfully register extension point", async () => {
+    const urlListPluginRepository = new UrlListPluginRepository(
+      new Set([PLUGIN_1_URL]),
+    );
+    const defaultPluginManager = new DefaultPluginManager([
+      urlListPluginRepository,
+    ]);
+
+    let extensions = await defaultPluginManager.getRegisteredExtensions(
+      EXTENSION_POINT_1,
+    );
+
+    expect(extensions.length).toEqual(0);
+
+    await defaultPluginManager.registerExtensions(EXTENSION_POINT_1);
+
+    extensions = await defaultPluginManager.getRegisteredExtensions(
+      EXTENSION_POINT_1,
+    );
+
+    expect(extensions.length).toEqual(1);
+  });
+
+  test("Registering an extension point twice has no effect", async () => {
+    const urlListPluginRepository = new UrlListPluginRepository(
+      new Set([PLUGIN_1_URL]),
+    );
+    const defaultPluginManager = new DefaultPluginManager([
+      urlListPluginRepository,
+    ]);
+
+    await defaultPluginManager.registerExtensions(EXTENSION_POINT_1);
+
+    let extensions = await defaultPluginManager.getRegisteredExtensions(
+      EXTENSION_POINT_1,
+    );
+
+    expect(extensions.length).toEqual(1);
+
+    await defaultPluginManager.registerExtensions(EXTENSION_POINT_1);
+
+    extensions = await defaultPluginManager.getRegisteredExtensions(
+      EXTENSION_POINT_1,
+    );
+
+    expect(extensions.length).toEqual(1);
+  });
+
+  test("Instantiating an extension works", async () => {
+    const urlListPluginRepository = new UrlListPluginRepository(
+      new Set([PLUGIN_1_URL]),
+    );
+    const defaultPluginManager = new DefaultPluginManager([
+      urlListPluginRepository,
+    ]);
+
+    await defaultPluginManager.registerExtensions(EXTENSION_POINT_1);
+
+    const extensionInfos = await defaultPluginManager.getRegisteredExtensions(
+      EXTENSION_POINT_1,
+    );
+
+    const extensionInfo = extensionInfos[0];
+
+    expect(extensionInfo.pluginData?.get("foo"), "bar");
+    expect(extensionInfo.extensionData?.get("foo"), "bar");
+
+    const instance = await defaultPluginManager.instantiate(
+      extensionInfo.extensionHandle,
+    ) as ExtensionPoint1;
+
+    expect(instance.sayHello()).toEqual("hello");
+  });
+});

package/tests/plugin_manager/plugin_repository/UrlListPluginRepository_test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import UrlListPluginRepository from "../../../src/plugin_manager/plugin_repository/UrlListPluginRepository.ts";
+import {
+  EXTENSION_POINT_1,
+  EXTENSION_POINT_2,
+} from "../../fixtures/Constants.ts";
+
+const PLUGIN_1_URL = "file://" +
+  path.join(
+    path.dirname(Bun.fileURLToPath(import.meta.url)),
+    "../../fixtures/ValidPlugin1.ts",
+  );
+
+describe("UrlPluginSource Tests", () => {
+  test("Throws on empty set of URLs", () => {
+    expect(() => new UrlListPluginRepository(new Set())).toThrow();
+  });
+
+  test("Throws on invalid URL", () => {
+    expect(() => new UrlListPluginRepository(new Set("foo"))).toThrow();
+  });
+
+  test("Successfully scans for matching plugin", async () => {
+    const urlSet = new Set<string>();
+    urlSet.add(PLUGIN_1_URL);
+
+    const pluginRepository = new UrlListPluginRepository(urlSet);
+
+    let count = 0;
+    for await (
+      const extensionEntry of pluginRepository.scanForExtensions(
+        EXTENSION_POINT_1,
+      )
+    ) {
+      expect(extensionEntry.pluginId).toEqual(PLUGIN_1_URL);
+      expect(extensionEntry.extensionPoint).toEqual(EXTENSION_POINT_1);
+      count += 1;
+    }
+    expect(count).toEqual(1);
+  });
+
+  test("Successfully scans for non-matching plugin", async () => {
+    const urlSet = new Set<string>();
+    urlSet.add(PLUGIN_1_URL);
+
+    const pluginRepository = new UrlListPluginRepository(urlSet);
+
+    let count = 0;
+    for await (
+      const extensionEntry of pluginRepository.scanForExtensions(
+        EXTENSION_POINT_2,
+      )
+    ) {
+      // this should not be called
+      expect(extensionEntry.pluginId, "not good");
+      count += 1;
+    }
+    expect(count).toEqual(0);
+  });
+});