every-plugin 0.8.9 → 2.2.2

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
+          ),
+      };
+    }),
+  },
+) {}

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

@@ -0,0 +1,254 @@
+import type { InferSchemaInput, InferSchemaOutput } from "@orpc/contract";
+import { Context, Effect, Scope } from "effect";
+import type { z } from "zod";
+import type {
+  AnyPlugin,
+  AnyPluginConstructor,
+  InitializedPlugin,
+  LoadedPlugin,
+  PluginInstance,
+  PluginMetadata,
+  PluginRegistry,
+} from "../../types";
+import { PluginRuntimeError, toPluginRuntimeError } from "../errors";
+import { validate } from "../validation";
+import { ModuleFederationService } from "./module-federation.service";
+import { SecretsService } from "./secrets.service";
+
+export class PluginRegistryTag extends Context.Tag("PluginRegistry")<
+  PluginRegistryTag,
+  PluginRegistry
+>() {}
+
+export class PluginMapTag extends Context.Tag("PluginMap")<
+  PluginMapTag,
+  Record<string, AnyPluginConstructor>
+>() {}
+
+export class RegistryService extends Effect.Service<RegistryService>()("RegistryService", {
+  effect: Effect.gen(function* () {
+    const registry = yield* PluginRegistryTag;
+    const pluginMap = yield* PluginMapTag;
+
+    return {
+      get: (pluginId: string) =>
+        Effect.gen(function* () {
+          const entry = registry[pluginId];
+
+          if (!entry) {
+            return yield* Effect.fail(
+              new PluginRuntimeError({
+                pluginId,
+                operation: "validate-plugin-id",
+                cause: new Error(`Plugin ${pluginId} not found in registry`),
+                retryable: false,
+              }),
+            );
+          }
+
+          if ("module" in entry) {
+            return {
+              constructor: entry.module,
+              metadata: {
+                remoteUrl: entry.remote || "",
+                version: entry.version,
+                description: entry.description,
+              } as PluginMetadata,
+            };
+          }
+
+          return {
+            constructor: null,
+            metadata: {
+              remoteUrl: entry.remote,
+              version: entry.version,
+              description: entry.description,
+            } as PluginMetadata,
+          };
+        }),
+
+      getModule: (pluginId: string) => Effect.succeed(pluginMap[pluginId] || null),
+    };
+  }),
+}) {}
+
+export class PluginLoaderService extends Effect.Service<PluginLoaderService>()(
+  "PluginLoaderService",
+  {
+    effect: Effect.gen(function* () {
+      const moduleFederationService = yield* ModuleFederationService;
+      const secretsService = yield* SecretsService;
+      const registryService = yield* RegistryService;
+
+      const resolveUrl = (baseUrl: string, version?: string): string =>
+        version && version !== "latest" ? baseUrl.replace("@latest", `@${version}`) : baseUrl;
+
+      return {
+        loadPlugin: (pluginId: string) =>
+          Effect.gen(function* () {
+            const entry = yield* registryService.get(pluginId);
+
+            if (entry.constructor) {
+              yield* Effect.logDebug("Loading plugin from direct module", { pluginId });
+
+              return {
+                ctor: entry.constructor,
+                metadata: entry.metadata,
+              } satisfies LoadedPlugin;
+            }
+
+            const url = entry.metadata.remoteUrl;
+            if (!url) {
+              return yield* Effect.fail(
+                new PluginRuntimeError({
+                  pluginId,
+                  operation: "load-plugin",
+                  cause: new Error(`Plugin ${pluginId} has no module or remote URL configured`),
+                  retryable: false,
+                }),
+              );
+            }
+
+            const resolvedUrl = resolveUrl(url);
+
+            yield* moduleFederationService
+              .registerRemote(pluginId, resolvedUrl)
+              .pipe(
+                Effect.mapError((error) =>
+                  toPluginRuntimeError(error, pluginId, undefined, "register-remote", true),
+                ),
+              );
+
+            yield* Effect.logDebug("Loading plugin from remote", { pluginId, url: resolvedUrl });
+
+            const ctor = yield* moduleFederationService
+              .loadRemoteConstructor(pluginId, resolvedUrl)
+              .pipe(
+                Effect.mapError((error) =>
+                  toPluginRuntimeError(error, pluginId, undefined, "load-remote", false),
+                ),
+              );
+
+            return {
+              ctor,
+              metadata: entry.metadata,
+            } satisfies LoadedPlugin;
+          }),
+
+        instantiatePlugin: <T extends AnyPlugin>(pluginId: string, loadedPlugin: LoadedPlugin<T>) =>
+          Effect.gen(function* () {
+            const instance = yield* Effect.try(() => new loadedPlugin.ctor()).pipe(
+              Effect.mapError((error) =>
+                toPluginRuntimeError(error, pluginId, undefined, "instantiate-plugin", false),
+              ),
+            );
+
+            (instance.id as string) = pluginId;
+
+            return {
+              plugin: instance,
+              metadata: loadedPlugin.metadata,
+            } satisfies PluginInstance<T>;
+          }),
+
+        initializePlugin: <T extends AnyPlugin>(
+          pluginInstance: PluginInstance<T>,
+          config: {
+            variables: InferSchemaInput<T["configSchema"]["variables"]>;
+            secrets: InferSchemaInput<T["configSchema"]["secrets"]>;
+          },
+          plugins?: Record<string, unknown>,
+        ) =>
+          Effect.gen(function* () {
+            const { plugin } = pluginInstance;
+
+            // Validate and hydrate config
+            const validatedVariables = yield* validate(
+              plugin.configSchema.variables as z.ZodSchema<
+                InferSchemaOutput<T["configSchema"]["variables"]>
+              >,
+              config.variables,
+              plugin.id,
+              "config",
+            ).pipe(
+              Effect.mapError(
+                (validationError) =>
+                  new PluginRuntimeError({
+                    pluginId: plugin.id,
+                    operation: "validate-config",
+                    cause: validationError.zodError,
+                    retryable: false,
+                  }),
+              ),
+            );
+
+            // Validate secrets
+            const validatedSecrets = yield* validate(
+              plugin.configSchema.secrets as z.ZodSchema<
+                InferSchemaOutput<T["configSchema"]["secrets"]>
+              >,
+              config.secrets,
+              plugin.id,
+              "config",
+            ).pipe(
+              Effect.mapError(
+                (validationError) =>
+                  new PluginRuntimeError({
+                    pluginId: plugin.id,
+                    operation: "validate-secrets",
+                    cause: validationError.zodError,
+                    retryable: false,
+                  }),
+              ),
+            );
+
+            // Hydrate secrets in variables
+            const hydratedConfig = yield* secretsService.hydrateSecrets({
+              variables: validatedVariables,
+              secrets: validatedSecrets,
+            });
+
+            const _variables = yield* validate(
+              plugin.configSchema.variables as z.ZodSchema<
+                InferSchemaOutput<T["configSchema"]["variables"]>
+              >,
+              hydratedConfig.variables,
+              plugin.id,
+              "config",
+            ).pipe(
+              Effect.mapError(
+                (validationError) =>
+                  new PluginRuntimeError({
+                    pluginId: plugin.id,
+                    operation: "validate-hydrated-config",
+                    cause: validationError.zodError,
+                    retryable: false,
+                  }),
+              ),
+            );
+
+            // Create a long-lived scope for this plugin instance
+            const scope = yield* Scope.make();
+
+            // Initialize plugin within the scope
+            const context = yield* plugin
+              .initialize({ variables: _variables, secrets: hydratedConfig.secrets }, plugins ?? {})
+              .pipe(
+                Effect.provideService(Scope.Scope, scope),
+                Effect.mapError((error) =>
+                  toPluginRuntimeError(error, plugin.id, undefined, "initialize-plugin", false),
+                ),
+              );
+
+            return {
+              plugin,
+              metadata: pluginInstance.metadata,
+              config: { variables: _variables, secrets: hydratedConfig.secrets },
+              context,
+              scope,
+            } satisfies InitializedPlugin<T>;
+          }),
+      };
+    }),
+  },
+) {}

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

@@ -0,0 +1,66 @@
+import { Effect, Exit, Layer, Scope } from "effect";
+import type {
+  AnyPlugin,
+  AnyPluginConstructor,
+  InitializedPlugin,
+  PluginRegistry,
+  SecretsConfig,
+} from "../../types";
+import { ModuleFederationService } from "./module-federation.service";
+import { PluginLifecycleService } from "./plugin-lifecycle.service";
+import {
+  PluginLoaderService,
+  PluginMapTag,
+  PluginRegistryTag,
+  RegistryService,
+} from "./plugin-loader.service";
+import { SecretsConfigTag, SecretsService } from "./secrets.service";
+
+export class PluginService extends Effect.Service<PluginService>()("PluginService", {
+  scoped: Effect.gen(function* () {
+    const loader = yield* PluginLoaderService;
+    const lifecycle = yield* PluginLifecycleService;
+
+    return {
+      loadPlugin: loader.loadPlugin,
+      instantiatePlugin: loader.instantiatePlugin,
+      initializePlugin: loader.initializePlugin,
+      shutdownPlugin: (plugin: InitializedPlugin<AnyPlugin>) =>
+        Effect.gen(function* () {
+          // Shutdown the plugin first (graceful cleanup)
+          yield* plugin.plugin.shutdown().pipe(Effect.catchAll(() => Effect.void));
+
+          // Close the plugin scope to interrupt fibers and release resources
+          yield* Scope.close(plugin.scope, Exit.succeed(undefined));
+
+          // Unregister from lifecycle tracking
+          yield* lifecycle.unregister(plugin);
+        }),
+      cleanup: lifecycle.cleanup,
+    };
+  }),
+}) {
+  static Live = (
+    registry: PluginRegistry,
+    secrets: SecretsConfig,
+    pluginMap: Record<string, AnyPluginConstructor> = {},
+  ) => {
+    const contextLayer = Layer.mergeAll(
+      Layer.succeed(PluginRegistryTag, registry),
+      Layer.succeed(SecretsConfigTag, secrets),
+      Layer.succeed(PluginMapTag, pluginMap),
+    );
+
+    const servicesLayer = Layer.mergeAll(
+      ModuleFederationService.Default,
+      SecretsService.Default,
+      RegistryService.Default,
+      PluginLifecycleService.Default,
+    ).pipe(Layer.provide(contextLayer));
+
+    return PluginService.Default.pipe(
+      Layer.provide(PluginLoaderService.Default),
+      Layer.provide(servicesLayer),
+    );
+  };
+}

package/src/runtime/services/secrets.service.ts

@@ -0,0 +1,74 @@
+import { Context, Effect } from "effect";
+import { z } from "zod";
+import type { SecretsConfig } from "../../types";
+import { PluginRuntimeError } from "../errors";
+
+const configSchema = z
+  .object({
+    secrets: z.record(z.string(), z.unknown()),
+  })
+  .loose();
+
+export class SecretsConfigTag extends Context.Tag("SecretsConfig")<
+  SecretsConfigTag,
+  SecretsConfig
+>() {}
+
+export class SecretsService extends Effect.Service<SecretsService>()("SecretsService", {
+  effect: Effect.gen(function* () {
+    const secrets = yield* SecretsConfigTag;
+
+    const hydrateValue = (value: unknown): unknown => {
+      if (typeof value === "string") {
+        let result = value;
+        for (const [key, secretValue] of Object.entries(secrets)) {
+          const pattern = new RegExp(`{{${key}}}`, "g");
+          result = result.replace(pattern, String(secretValue));
+        }
+        return result;
+      }
+
+      if (Array.isArray(value)) {
+        return value.map(hydrateValue);
+      }
+
+      if (value && typeof value === "object") {
+        const isPlainObject = value.constructor === Object || value.constructor === undefined;
+
+        if (isPlainObject) {
+          const hydrated: Record<string, unknown> = {};
+          for (const [key, val] of Object.entries(value)) {
+            hydrated[key] = hydrateValue(val);
+          }
+          return hydrated;
+        }
+
+        const hydrated = Object.create(Object.getPrototypeOf(value));
+        for (const [key, val] of Object.entries(value)) {
+          hydrated[key] = hydrateValue(val);
+        }
+        return hydrated;
+      }
+
+      return value;
+    };
+
+    return {
+      hydrateSecrets: <T>(config: T) =>
+        Effect.gen(function* () {
+          const parseResult = configSchema.parse(config);
+          try {
+            return hydrateValue(parseResult) as T;
+          } catch (error) {
+            return yield* Effect.fail(
+              new PluginRuntimeError({
+                operation: "hydrate-secrets",
+                cause: error instanceof Error ? error : new Error(String(error)),
+                retryable: false,
+              }),
+            );
+          }
+        }),
+    };
+  }),
+}) {}

package/src/runtime/services.ts

@@ -0,0 +1,5 @@
+export * from "./services/module-federation.service";
+export * from "./services/plugin.service";
+export * from "./services/plugin-lifecycle.service";
+export * from "./services/plugin-loader.service";
+export * from "./services/secrets.service";