every-plugin 0.9.0 → 2.2.2

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";

package/src/runtime/validation.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import type { z } from "zod";
+import { ValidationError } from "./errors";
+
+export const validate = <T>(
+  schema: z.ZodSchema<T>,
+  data: unknown,
+  pluginId: string,
+  stage: "config" | "input" | "output" | "state",
+): Effect.Effect<T, ValidationError> =>
+  Effect.gen(function* () {
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return result.data;
+    }
+    return yield* Effect.fail(
+      new ValidationError({
+        pluginId,
+        stage,
+        zodError: result.error,
+      }),
+    );
+  });

package/src/testing/index.ts

@@ -0,0 +1,87 @@
+import type { LoadedPluginWithBinding } from "../plugin";
+import { createPluginRuntime } from "../runtime";
+import type { AnyPluginConstructor, PluginRegistryEntry, PluginRuntimeConfig } from "../types";
+
+export type PluginMap = Record<string, LoadedPluginWithBinding<any, any, any, any>>;
+
+/**
+ * Simplified type inference for local plugin maps.
+ * Just use the constructor types directly.
+ *
+ * @example
+ * ```ts
+ * const pluginMap = { "my-plugin": MyPlugin } as const;
+ * type MyBindings = InferBindingsFromMap<typeof pluginMap>;
+ * ```
+ */
+export type InferBindingsFromMap<T extends PluginMap> = {
+  [K in keyof T]: T[K];
+};
+
+/**
+ * Converts old pluginMap format to new registry format
+ */
+function convertPluginMapToRegistry<T extends PluginMap>(
+  oldRegistry: Record<string, { remoteUrl: string; version?: string; description?: string }>,
+  pluginMap: T,
+): Record<keyof T, PluginRegistryEntry> {
+  const registry: Record<string, PluginRegistryEntry> = {};
+
+  for (const [pluginId, ctor] of Object.entries(pluginMap)) {
+    const oldEntry = oldRegistry[pluginId];
+    registry[pluginId] = {
+      module: ctor as AnyPluginConstructor,
+      remote: oldEntry?.remoteUrl,
+      version: oldEntry?.version,
+      description: oldEntry?.description,
+    };
+  }
+
+  return registry as Record<keyof T, PluginRegistryEntry>;
+}
+
+/**
+ * Creates a plugin runtime for locally available plugins (non-remote).
+ * Automatically infers type bindings from the plugin map, eliminating
+ * the need for manual RegistryBindings definitions.
+ *
+ * @deprecated Use `createPluginRuntime` with module entries directly instead.
+ * @example
+ * ```ts
+ * // Old API (deprecated)
+ * const runtime = createLocalPluginRuntime(
+ *   { registry: { "my-plugin": { remoteUrl: "..." } }, secrets },
+ *   { "my-plugin": MyPlugin }
+ * );
+ *
+ * // New API (recommended)
+ * const runtime = createPluginRuntime({
+ *   registry: { "my-plugin": { module: MyPlugin } },
+ *   secrets
+ * });
+ * ```
+ */
+export function createLocalPluginRuntime<TMap extends PluginMap>(
+  config: {
+    registry: Record<string, { remoteUrl: string; version?: string; description?: string }>;
+    secrets?: Record<string, string>;
+    options?: any;
+  },
+  pluginMap: TMap,
+) {
+  const newRegistry = convertPluginMapToRegistry(config.registry, pluginMap);
+
+  return createPluginRuntime({
+    registry: newRegistry,
+    secrets: config.secrets,
+    options: config.options,
+  });
+}
+
+/**
+ * @deprecated Use `createLocalPluginRuntime` or `createPluginRuntime` instead.
+ */
+export const createTestPluginRuntime = createLocalPluginRuntime;
+
+export type { EveryPlugin, PluginRegistry, RegisteredPlugins } from "../types";
+export type { PluginRuntimeConfig };

package/src/testing/mocks/module-federation.service.ts

@@ -0,0 +1,41 @@
+import { Effect, Layer } from "effect";
+import type { LoadedPluginWithBinding } from "../../plugin";
+import { ModuleFederationError } from "../../runtime/errors";
+import { ModuleFederationService } from "../../runtime/services/module-federation.service";
+
+export type PluginMap = Record<string, LoadedPluginWithBinding<any, any, any, any>>;
+
+export const createMockModuleFederationServiceLayer = (pluginMap: PluginMap) =>
+  Layer.succeed(ModuleFederationService, {
+    registerRemote: (pluginId: string, url: string) =>
+      Effect.gen(function* () {
+        console.log(`[MOCK] registerRemote called for ${pluginId}`);
+        if (!(pluginId in pluginMap)) {
+          return yield* Effect.fail(
+            new ModuleFederationError({
+              pluginId,
+              remoteUrl: url,
+              cause: new Error(`Mock: Plugin ${pluginId} not available in test plugin map`),
+            }),
+          );
+        }
+        console.log(`[MOCK] registerRemote succeeded for ${pluginId}`);
+      }),
+
+    loadRemoteConstructor: (pluginId: string, url: string) =>
+      Effect.gen(function* () {
+        console.log(`[MOCK] loadRemoteConstructor called for ${pluginId}`);
+        const PluginConstructor = pluginMap[pluginId];
+        if (!PluginConstructor) {
+          return yield* Effect.fail(
+            new ModuleFederationError({
+              pluginId,
+              remoteUrl: url,
+              cause: new Error(`Mock: Constructor for ${pluginId} not found in test plugin map`),
+            }),
+          );
+        }
+        console.log(`[MOCK] loadRemoteConstructor succeeded for ${pluginId}`);
+        return PluginConstructor;
+      }),
+  } as any);