every-plugin 0.9.0 → 2.2.2

package/src/runtime/index.ts

@@ -0,0 +1,258 @@
+import { createRouterClient } from "@orpc/server";
+import { Cause, Effect, Exit, Hash, ManagedRuntime, Option } from "effect";
+import type {
+  AnyPlugin,
+  AnyPluginConstructor,
+  InferRegistryFromEntries,
+  InitializedPlugin,
+  LoadedPlugin,
+  PluginConfigInput,
+  PluginInstance,
+  PluginRegistry,
+  PluginRegistryEntry,
+  PluginRouterType,
+  PluginRuntimeConfig,
+  RegisteredPlugin,
+  RegisteredPlugins,
+  UsePluginResult,
+} from "../types";
+import { PluginRuntimeError } from "./errors";
+import { PluginService } from "./services/plugin.service";
+
+export class PluginRuntime<R = RegisteredPlugins> {
+  readonly __registryType?: R;
+
+  private pluginCache = new Map<
+    string,
+    Effect.Effect<InitializedPlugin<AnyPlugin>, PluginRuntimeError>
+  >();
+
+  constructor(
+    private runtime: ManagedRuntime.ManagedRuntime<PluginService, never>,
+    private registry: PluginRegistry,
+  ) {}
+
+  private generateCacheKey(pluginId: string, config: unknown): string {
+    const configHash = Hash.structure(config as object).toString();
+    return `${pluginId}:${configHash}`;
+  }
+
+  private validatePluginId(pluginId: string): Effect.Effect<string, PluginRuntimeError> {
+    if (!(pluginId in this.registry)) {
+      return Effect.fail(
+        new PluginRuntimeError({
+          pluginId: String(pluginId),
+          operation: "validate-plugin-id",
+          cause: new Error(`Plugin ID '${String(pluginId)}' not found in registry.`),
+          retryable: false,
+        }),
+      );
+    }
+    return Effect.succeed(String(pluginId));
+  }
+
+  private async runPromise<A, E>(effect: Effect.Effect<A, E, PluginService>): Promise<A> {
+    const exit = await this.runtime.runPromiseExit(effect);
+
+    if (Exit.isFailure(exit)) {
+      const error = Cause.failureOption(exit.cause);
+      if (Option.isSome(error)) {
+        throw error.value;
+      }
+      throw Cause.squash(exit.cause);
+    }
+
+    return exit.value;
+  }
+
+  async usePlugin<K extends keyof R & string>(
+    pluginId: K,
+    config: PluginConfigInput<R[K]>,
+    plugins?: Record<string, unknown>,
+  ): Promise<UsePluginResult<K, R>> {
+    const cacheKey = this.generateCacheKey(pluginId, { ...config, __plugins: plugins ?? {} });
+
+    let cachedPlugin = this.pluginCache.get(cacheKey);
+    if (!cachedPlugin) {
+      const operation = Effect.gen(this, function* () {
+        const pluginService = yield* PluginService;
+        const validatedId = yield* this.validatePluginId(pluginId);
+
+        // Load → Instantiate → Initialize
+        const ctor = yield* pluginService.loadPlugin(validatedId);
+        const instance = yield* pluginService.instantiatePlugin(pluginId, ctor);
+        const initialized = yield* pluginService.initializePlugin(instance, config, plugins);
+
+        return initialized;
+      }).pipe(Effect.provide(this.runtime));
+
+      cachedPlugin = Effect.cached(operation).pipe(Effect.flatten);
+      this.pluginCache.set(cacheKey, cachedPlugin);
+    }
+
+    const initialized = await this.runPromise(cachedPlugin);
+
+    // Create client factory that accepts request context
+    const createClient = (context?: any) => {
+      const router = initialized.plugin.createRouter(initialized.context);
+      return createRouterClient(router, { context: context ?? {} });
+    };
+
+    return {
+      createClient: createClient as any,
+      router: initialized.plugin.createRouter(initialized.context) as PluginRouterType<R[K]>,
+      metadata: initialized.metadata,
+      initialized: initialized as InitializedPlugin<RegisteredPlugin<K, R>>,
+    } as UsePluginResult<K, R>;
+  }
+
+  async loadPlugin<K extends keyof R & string>(
+    pluginId: K,
+  ): Promise<LoadedPlugin<RegisteredPlugin<K, R>>> {
+    const effect = Effect.gen(function* () {
+      const pluginService = yield* PluginService;
+      return yield* pluginService.loadPlugin(pluginId);
+    });
+    return this.runPromise(effect) as Promise<LoadedPlugin<RegisteredPlugin<K, R>>>;
+  }
+
+  async instantiatePlugin<K extends keyof R & string>(
+    pluginId: K,
+    loadedPlugin: LoadedPlugin<RegisteredPlugin<K, R>>,
+  ): Promise<PluginInstance<RegisteredPlugin<K, R>>> {
+    const effect = Effect.gen(function* () {
+      const pluginService = yield* PluginService;
+      return yield* pluginService.instantiatePlugin(pluginId, loadedPlugin);
+    });
+    return this.runPromise(effect) as Promise<PluginInstance<RegisteredPlugin<K, R>>>;
+  }
+
+  async initializePlugin<T extends AnyPlugin>(
+    instance: PluginInstance<T>,
+    config: any,
+    plugins?: Record<string, unknown>,
+  ): Promise<InitializedPlugin<T>> {
+    const effect = Effect.gen(function* () {
+      const pluginService = yield* PluginService;
+      return yield* pluginService.initializePlugin(instance, config, plugins);
+    });
+    return this.runPromise(effect);
+  }
+
+  async shutdown(): Promise<void> {
+    const effect = Effect.gen(function* () {
+      const pluginService = yield* PluginService;
+      yield* pluginService.cleanup();
+    });
+    return this.runPromise(effect);
+  }
+
+  async evictPlugin<K extends keyof R & string>(
+    pluginId: K,
+    config: PluginConfigInput<R[K]>,
+  ): Promise<void> {
+    const cacheKey = this.generateCacheKey(pluginId, config);
+
+    const effect = Effect.gen(this, function* () {
+      const pluginService = yield* PluginService;
+      const cachedPlugin = this.pluginCache.get(cacheKey);
+
+      if (cachedPlugin) {
+        this.pluginCache.delete(cacheKey);
+
+        const pluginResult = yield* cachedPlugin.pipe(Effect.catchAll(() => Effect.succeed(null)));
+
+        if (pluginResult) {
+          yield* pluginService
+            .shutdownPlugin(pluginResult)
+            .pipe(Effect.catchAll(() => Effect.void));
+        }
+      }
+    }).pipe(Effect.catchAll(() => Effect.void));
+
+    return this.runPromise(effect);
+  }
+}
+
+/**
+ * Normalizes a remote URL to ensure it points to remoteEntry.js
+ * If the URL doesn't end with a file extension, appends /remoteEntry.js
+ */
+function normalizeRemoteUrl(url: string): string {
+  if (!url) return url;
+  if (url.endsWith(".js") || url.endsWith(".json")) return url;
+  return `${url.endsWith("/") ? url.slice(0, -1) : url}/remoteEntry.js`;
+}
+
+/**
+ * Extract plugin map (module constructors) from registry entries
+ */
+function extractPluginMap(
+  registry: Record<string, PluginRegistryEntry>,
+): Record<string, AnyPluginConstructor> {
+  const pluginMap: Record<string, AnyPluginConstructor> = {};
+
+  for (const [pluginId, entry] of Object.entries(registry)) {
+    if ("module" in entry && entry.module) {
+      pluginMap[pluginId] = entry.module;
+    }
+  }
+
+  return pluginMap;
+}
+
+/**
+ * Normalize registry entries - ensure remote URLs are properly formatted
+ */
+function normalizeRegistry(registry: Record<string, PluginRegistryEntry>): PluginRegistry {
+  const normalized: Record<string, PluginRegistryEntry> = {};
+
+  for (const [pluginId, entry] of Object.entries(registry)) {
+    if ("module" in entry) {
+      normalized[pluginId] = {
+        ...entry,
+        remote: entry.remote ? normalizeRemoteUrl(entry.remote) : undefined,
+      };
+    } else {
+      normalized[pluginId] = {
+        ...entry,
+        remote: normalizeRemoteUrl(entry.remote),
+      };
+    }
+  }
+
+  return normalized as PluginRegistry;
+}
+
+/**
+ * Creates a plugin runtime with support for both module and remote plugin entries.
+ *
+ * @example
+ * ```typescript
+ * // With module entries (types inferred automatically)
+ * const runtime = createPluginRuntime({
+ *   registry: {
+ *     telegram: { module: TelegramPlugin },
+ *     gopher: { remote: "https://cdn.example.com/gopher/remoteEntry.js" }
+ *   },
+ *   secrets: { API_KEY: "..." }
+ * });
+ *
+ * // Types are automatically inferred from module entries!
+ * const { router } = await runtime.usePlugin("telegram", config);
+ * ```
+ */
+export function createPluginRuntime<TRegistry extends Record<string, PluginRegistryEntry>>(
+  config: PluginRuntimeConfig<TRegistry>,
+): PluginRuntime<InferRegistryFromEntries<TRegistry>> {
+  const secrets = config.secrets || {};
+  const normalizedRegistry = normalizeRegistry(config.registry);
+  const pluginMap = extractPluginMap(config.registry);
+
+  const layer = PluginService.Live(normalizedRegistry, secrets, pluginMap);
+  const runtime = ManagedRuntime.make(layer);
+
+  return new PluginRuntime(runtime, normalizedRegistry) as PluginRuntime<
+    InferRegistryFromEntries<TRegistry>
+  >;
+}

package/src/runtime/mf-config.ts

@@ -0,0 +1,29 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json") as { version: string };
+export const PLUGIN_VERSION = pkg.version;
+
+export const SHARE_CONFIG = {
+  singleton: true,
+  requiredVersion: false,
+  strictVersion: false,
+  eager: false,
+} as const;
+
+export const MF_SHARED_DEPS = {
+  "every-plugin": {
+    version: PLUGIN_VERSION,
+    shareConfig: SHARE_CONFIG,
+  },
+  effect: {
+    version: "^3.21.0",
+    shareConfig: SHARE_CONFIG,
+  },
+  zod: {
+    version: "^4.3.6",
+    shareConfig: SHARE_CONFIG,
+  },
+} as const;
+
+export type SharedDepName = keyof typeof MF_SHARED_DEPS;

package/src/runtime/services/module-federation.service.ts

@@ -0,0 +1,181 @@
+import { createInstance, getInstance } from "@module-federation/enhanced/runtime";
+import { setGlobalFederationInstance } from "@module-federation/runtime-core";
+import { Effect } from "effect";
+import type { AnyPlugin } from "../../types";
+import { ModuleFederationError } from "../errors";
+import { MF_SHARED_DEPS, type SharedDepName } from "../mf-config";
+import { getNormalizedRemoteName } from "./normalize";
+
+type RemoteModule = (new () => AnyPlugin) | { default: new () => AnyPlugin };
+
+const sharedModuleLoaders = {
+  "every-plugin": () => import("every-plugin"),
+  effect: () => import("effect"),
+  zod: () => import("zod"),
+} satisfies Record<SharedDepName, () => Promise<unknown>>;
+
+const createModuleFederationInstance = Effect.cached(
+  Effect.sync(() => {
+    try {
+      let instance = getInstance();
+
+      if (!instance) {
+        const shared = Object.fromEntries(
+          (
+            Object.entries(MF_SHARED_DEPS) as [
+              SharedDepName,
+              (typeof MF_SHARED_DEPS)[SharedDepName],
+            ][]
+          ).map(([name, config]) => {
+            const load = sharedModuleLoaders[name];
+
+            if (!load) {
+              throw new Error(`Missing shared module loader for ${name}`);
+            }
+
+            return [
+              name,
+              {
+                version: config.version,
+                get: () => load().then((mod) => () => mod),
+                shareConfig: config.shareConfig,
+              },
+            ];
+          }),
+        );
+
+        instance = createInstance({
+          name: "host",
+          remotes: [],
+          shared,
+        });
+
+        setGlobalFederationInstance(instance);
+      }
+
+      return instance;
+    } catch (error) {
+      throw new Error(`Failed to initialize Module Federation: ${error}`);
+    }
+  }),
+);
+
+export class ModuleFederationService extends Effect.Service<ModuleFederationService>()(
+  "ModuleFederationService",
+  {
+    effect: Effect.gen(function* () {
+      const mf = yield* Effect.flatten(createModuleFederationInstance);
+
+      return {
+        registerRemote: (pluginId: string, url: string) =>
+          Effect.gen(function* () {
+            console.log(`[MF] Registering ${pluginId}`);
+
+            const remoteName = getNormalizedRemoteName(pluginId);
+            const type = url.endsWith("/mf-manifest.json")
+              ? ("manifest" as const)
+              : url.endsWith("/remoteEntry.js")
+                ? ("script" as const)
+                : undefined;
+
+            yield* Effect.try({
+              try: () =>
+                mf.registerRemotes([
+                  {
+                    name: remoteName,
+                    entry: url,
+                    ...(type ? { type } : {}),
+                  },
+                ]),
+              catch: (error): ModuleFederationError =>
+                new ModuleFederationError({
+                  pluginId,
+                  remoteUrl: url,
+                  cause: error instanceof Error ? error : new Error(String(error)),
+                }),
+            });
+
+            console.log(`[MF] ✅ Registered ${pluginId}`);
+          }),
+
+        loadRemoteConstructor: (pluginId: string, url: string) =>
+          Effect.gen(function* () {
+            const remoteName = getNormalizedRemoteName(pluginId);
+            console.log(`[MF] Loading remote ${remoteName}`);
+            const modulePath = `${remoteName}/plugin`;
+
+            return yield* Effect.tryPromise({
+              try: async () => {
+                const container = await mf.loadRemote<RemoteModule>(modulePath);
+                if (!container) {
+                  throw new Error(`No container returned for ${modulePath}`);
+                }
+
+                // Support multiple export patterns: direct function, default export, named exports
+                let Constructor: any;
+
+                if (typeof container === "function") {
+                  // Direct function export
+                  Constructor = container;
+                } else if (container.default) {
+                  // Default export
+                  Constructor = container.default;
+                } else {
+                  // Named export fallback - prioritize exports with 'binding' property (plugin classes)
+                  Constructor = Object.values(container).find(
+                    (exp) => typeof exp === "function" && (exp as any).binding !== undefined,
+                  );
+
+                  // Fallback to any function export if no binding found
+                  if (!Constructor) {
+                    Constructor = Object.values(container).find(
+                      (exp) => typeof exp === "function" && exp.prototype?.constructor === exp,
+                    );
+                  }
+                }
+
+                if (!Constructor || typeof Constructor !== "function") {
+                  const containerInfo =
+                    typeof container === "object"
+                      ? `Available exports: ${Object.keys(container).join(", ")}`
+                      : `Container type: ${typeof container}`;
+
+                  throw new Error(
+                    `No valid plugin constructor found for '${pluginId}'.\n` +
+                      `Supported patterns:\n` +
+                      `  - export const YourPlugin = createPlugin({...})\n` +
+                      `  - export default createPlugin({...})\n` +
+                      `${containerInfo}`,
+                  );
+                }
+
+                // Validate it looks like a plugin constructor (has binding property)
+                if (!(Constructor as any).binding) {
+                  const containerInfo =
+                    typeof container === "object"
+                      ? `Found exports: ${Object.keys(container).join(", ")}`
+                      : `Container type: ${typeof container}`;
+
+                  throw new Error(
+                    `Invalid plugin constructor for '${pluginId}'. ` +
+                      `The exported value must be created with createPlugin(). ` +
+                      `Found a function but it's missing the required 'binding' property.\n` +
+                      `${containerInfo}`,
+                  );
+                }
+
+                console.log(`[MF] ✅ Loaded constructor for ${pluginId}`);
+                return Constructor;
+              },
+              catch: (error): ModuleFederationError =>
+                new ModuleFederationError({
+                  pluginId,
+                  remoteUrl: url,
+                  cause: error instanceof Error ? error : new Error(String(error)),
+                }),
+            });
+          }),
+      };
+    }),
+  },
+) {}

package/src/runtime/services/normalize.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalizes a package name into the module federation remote name.
+ * This function must produce identical results in both runtime and build contexts.
+ *
+ * Normalization rules:
+ * - Convert to lowercase
+ * - Strip a single leading '@' symbol
+ * - Replace '/' with '_'
+ * - Preserve hyphens and other characters
+ *
+ * Examples:
+ * - "@scope/my-plugin" → "scope_my-plugin"
+ * - "@SCOPE/Foo/Bar" → "scope_foo_bar"
+ * - "foo/bar" → "foo_bar"
+ * - "simple-plugin" → "simple-plugin"
+ */
+export const getNormalizedRemoteName = (name: string): string =>
+  name.toLowerCase().replace(/^@/, "").replace(/\//g, "_");

package/src/runtime/services/plugin-lifecycle.service.ts

@@ -0,0 +1,86 @@
+import { Effect, Ref } from "effect";
+import type { AnyPlugin, InitializedPlugin } from "../../types";
+import { toPluginRuntimeError } from "../errors";
+
+export class PluginLifecycleService extends Effect.Service<PluginLifecycleService>()(
+  "PluginLifecycleService",
+  {
+    effect: Effect.gen(function* () {
+      const activePlugins = yield* Ref.make(new Set<InitializedPlugin<AnyPlugin>>());
+
+      return {
+        register: <T extends AnyPlugin>(plugin: InitializedPlugin<T>) =>
+          Ref.update(activePlugins, (plugins) =>
+            new Set(plugins).add(plugin as InitializedPlugin<AnyPlugin>),
+          ),
+
+        unregister: (plugin: InitializedPlugin<AnyPlugin>) =>
+          Ref.update(activePlugins, (plugins) => {
+            const newSet = new Set(plugins);
+            newSet.delete(plugin);
+            return newSet;
+          }),
+
+        shutdown: (plugin: InitializedPlugin<AnyPlugin>) =>
+          Effect.gen(function* () {
+            // Remove from active plugins
+            yield* Ref.update(activePlugins, (plugins) => {
+              const newSet = new Set(plugins);
+              newSet.delete(plugin);
+              return newSet;
+            });
+
+            // Shutdown the plugin
+            yield* plugin.plugin
+              .shutdown()
+              .pipe(
+                Effect.mapError((error) =>
+                  toPluginRuntimeError(
+                    error,
+                    plugin.plugin.id,
+                    undefined,
+                    "shutdown-plugin",
+                    false,
+                  ),
+                ),
+              );
+          }),
+
+        cleanup: () =>
+          Effect.gen(function* () {
+            const plugins = yield* Ref.get(activePlugins);
+
+            // Shutdown all active plugins concurrently
+            yield* Effect.forEach(
+              plugins,
+              (plugin) =>
+                plugin.plugin.shutdown().pipe(
+                  Effect.mapError((error) =>
+                    toPluginRuntimeError(
+                      error,
+                      plugin.plugin.id,
+                      undefined,
+                      "cleanup-shutdown",
+                      false,
+                    ),
+                  ),
+                  Effect.catchAll((error) =>
+                    Effect.logError(
+                      `Failed to shutdown plugin ${plugin.plugin.id} during cleanup`,
+                      error,
+                      { pluginId: plugin.plugin.id },
+                    ),
+                  ),
+                ),
+              { concurrency: "unbounded" },
+            );
+
+            // Clear the active plugins set
+            yield* Ref.set(activePlugins, new Set());
+          }).pipe(
+            Effect.catchAll(() => Effect.void), // Convert errors to void for cleanup
+          ),
+      };
+    }),
+  },
+) {}