every-plugin 2.10.1 → 3.0.0-rc.3

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

@@ -1,7 +1,7 @@
 import type { InferSchemaInput, InferSchemaOutput } from "@orpc/contract";
-import { Context, Effect, Context as EffectContext, Exit, Layer, Scope } from "effect";
+import { Context, Effect, Exit, Layer, Scope } from "effect";
 import type { z } from "zod";
-import { PluginIdTag, type PluginServicesTools } from "../../plugin";
+import { PluginIdTag } from "../../plugin";
 import type {
   AnyPlugin,
   AnyPluginConstructor,
@@ -11,23 +11,65 @@ import type {
   PluginMetadata,
   PluginRegistry,
 } from "../../types";
+import type { PluginWarningInfo } from "../errors";
 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
->() {}
+/**
+ * Evaluate a plugin's `warnings` function against the validated config.
+ * Fail-safe: a throwing warnings function becomes a warning itself rather
+ * than failing initialization. Strings are normalized to `PluginWarningInfo`
+ * with the plugin's registry key.
+ */
+const collectPluginWarnings = (
+  plugin: AnyPlugin,
+  config: { variables: unknown; secrets: unknown },
+): PluginWarningInfo[] => {
+  const warningsFn = plugin.warnings;
+  if (!warningsFn) return [];
+  try {
+    const raw = warningsFn(config as never);
+    return raw.map((warning) =>
+      typeof warning === "string" ? { pluginKey: plugin.id, message: warning } : warning,
+    );
+  } catch (error) {
+    return [
+      {
+        pluginKey: plugin.id,
+        message: `Plugin warnings check failed: ${error instanceof Error ? error.message : String(error)}`,
+      },
+    ];
+  }
+};
+
+export class PluginRegistryTag extends Context.Service<PluginRegistryTag, PluginRegistry>()(
+  "PluginRegistry",
+) {}
 
-export class PluginMapTag extends Context.Tag("PluginMap")<
+export class PluginMapTag extends Context.Service<
   PluginMapTag,
   Record<string, AnyPluginConstructor>
->() {}
+>()("PluginMap") {}
+
+export interface RegistryServiceShape {
+  get: (
+    pluginId: string,
+  ) => Effect.Effect<
+    { constructor: (new () => AnyPlugin) | null; metadata: PluginMetadata },
+    PluginRuntimeError
+  >;
+  getModule: (pluginId: string) => Effect.Effect<AnyPluginConstructor | null>;
+}
+
+export class RegistryService extends Context.Service<RegistryService, RegistryServiceShape>()(
+  "RegistryService",
+) {}
 
-export class RegistryService extends Effect.Service<RegistryService>()("RegistryService", {
-  effect: Effect.gen(function* () {
+export const RegistryServiceDefault = Layer.effect(
+  RegistryService,
+  Effect.gen(function* () {
     const registry = yield* PluginRegistryTag;
     const pluginMap = yield* PluginMapTag;
 
@@ -37,14 +79,11 @@ export class RegistryService extends Effect.Service<RegistryService>()("Registry
           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,
-              }),
-            );
+            return yield* new PluginRuntimeError({
+              pluginId,
+              operation: "validate-plugin-id",
+              cause: new Error(`Plugin ${pluginId} not found in registry`),
+            });
           }
 
           if ("module" in entry) {
@@ -71,223 +110,243 @@ export class RegistryService extends Effect.Service<RegistryService>()("Registry
       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);
+);
+
+export interface PluginLoaderServiceShape {
+  loadPlugin: (pluginId: string) => Effect.Effect<LoadedPlugin, PluginRuntimeError>;
+  instantiatePlugin: <T extends AnyPlugin>(
+    pluginId: string,
+    loadedPlugin: LoadedPlugin<T>,
+  ) => Effect.Effect<PluginInstance<T>, PluginRuntimeError>;
+  initializePlugin: <T extends AnyPlugin>(
+    pluginInstance: PluginInstance<T>,
+    config: {
+      variables: InferSchemaInput<T["configSchema"]["variables"]>;
+      secrets: InferSchemaInput<T["configSchema"]["secrets"]>;
+    },
+    plugins?: Record<string, unknown>,
+  ) => Effect.Effect<InitializedPlugin<T>, PluginRuntimeError>;
+}
+
+export class PluginLoaderService extends Context.Service<
+  PluginLoaderService,
+  PluginLoaderServiceShape
+>()("PluginLoaderService") {}
+
+export const PluginLoaderServiceDefault = Layer.effect(
+  PluginLoaderService,
+  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;
 
-            yield* moduleFederationService.registerRemote(pluginId, resolvedUrl).pipe(
-              Effect.tapError((error) =>
-                Effect.logError(`Plugin ${pluginId} failed during register-remote: ${error}`),
-              ),
-              Effect.mapError((error) =>
-                toPluginRuntimeError(error, pluginId, undefined, "register-remote", true),
-              ),
-            );
-
-            yield* Effect.logDebug("Loading plugin from remote", { pluginId, url: resolvedUrl });
+    return {
+      loadPlugin: (pluginId: string) =>
+        Effect.gen(function* () {
+          const entry = yield* registryService.get(pluginId);
 
-            const ctor = yield* moduleFederationService
-              .loadRemoteConstructor(pluginId, resolvedUrl)
-              .pipe(
-                Effect.tapError((error) =>
-                  Effect.logError(`Plugin ${pluginId} failed during load-remote: ${error}`),
-                ),
-                Effect.mapError((error) =>
-                  toPluginRuntimeError(error, pluginId, undefined, "load-remote", false),
-                ),
-              );
+          if (entry.constructor) {
+            yield* Effect.logDebug("Loading plugin from direct module", { pluginId });
 
             return {
-              ctor,
+              ctor: entry.constructor,
               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.tapError((error) =>
-                Effect.logError(`Plugin ${pluginId} failed during instantiate-plugin: ${error}`),
-              ),
-              Effect.mapError((error) =>
-                toPluginRuntimeError(error, pluginId, undefined, "instantiate-plugin", false),
-              ),
-            );
+          const url = entry.metadata.remoteUrl;
+          if (!url) {
+            return yield* new PluginRuntimeError({
+              pluginId,
+              operation: "load-plugin",
+              cause: new Error(`Plugin ${pluginId} has no module or remote URL configured`),
+            });
+          }
 
-            (instance.id as string) = pluginId;
+          const resolvedUrl = resolveUrl(url);
 
-            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,
-                  }),
-              ),
-            );
+          yield* moduleFederationService.registerRemote(pluginId, resolvedUrl).pipe(
+            Effect.tapError((error) =>
+              Effect.logError(`Plugin ${pluginId} failed during register-remote: ${String(error)}`),
+            ),
+            Effect.mapError((error) =>
+              toPluginRuntimeError(error, pluginId, undefined, "register-remote"),
+            ),
+          );
 
-            // 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,
-                  }),
-              ),
-            );
+          yield* Effect.logDebug("Loading plugin from remote", { pluginId, url: resolvedUrl });
 
-            // 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,
-                  }),
+          const ctor = yield* moduleFederationService
+            .loadRemoteConstructor(pluginId, resolvedUrl)
+            .pipe(
+              Effect.tapError((error) =>
+                Effect.logError(`Plugin ${pluginId} failed during load-remote: ${String(error)}`),
+              ),
+              Effect.mapError((error) =>
+                toPluginRuntimeError(error, pluginId, undefined, "load-remote"),
               ),
             );
 
-            // Create a long-lived scope for this plugin instance
-            const scope = yield* Scope.make();
+          return {
+            ctor,
+            metadata: entry.metadata,
+          } satisfies LoadedPlugin;
+        }),
 
-            // Create a per-plugin MemoMap so tool-built layers are memoized
-            const memoMap = yield* Layer.makeMemoMap;
+      instantiatePlugin: <T extends AnyPlugin>(pluginId: string, loadedPlugin: LoadedPlugin<T>) =>
+        Effect.gen(function* () {
+          const instance = yield* Effect.try(() => new loadedPlugin.ctor()).pipe(
+            Effect.tapError((error) =>
+              Effect.logError(`Plugin ${pluginId} failed during instantiate-plugin: ${error}`),
+            ),
+            Effect.mapError((error) =>
+              toPluginRuntimeError(error, pluginId, undefined, "instantiate-plugin"),
+            ),
+          );
 
-            const tools: PluginServicesTools = {
-              buildService: (tag: any, layer: any) =>
-                (Layer.buildWithMemoMap(layer, memoMap, scope) as any).pipe(
-                  Effect.map((ctx: any) => EffectContext.get(ctx, tag)) as any,
-                ),
-            };
+          (instance.id as string) = pluginId;
 
-            // Initialize plugin within the scope.
-            // If initialize fails, close the scope immediately so scoped
-            // resources (DB pools, caches) are released — otherwise every
-            // failed initialization leaks until the process exits.
-            const context = yield* plugin
-              .initialize(
-                { variables: _variables, secrets: hydratedConfig.secrets },
-                plugins ?? {},
-                tools,
-              )
+          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,
+                }),
+            ),
+          );
+
+          // 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,
+                }),
+            ),
+          );
+
+          // 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,
+                }),
+            ),
+          );
+
+          // Create a long-lived scope for this plugin instance. Initialize
+          // returns a Layer which is built against this scope, so scoped
+          // resources (DB pools, caches) release on plugin shutdown.
+          const scope = yield* Scope.make();
+
+          // Build the plugin's Layer within the scope.
+          // On failure, close the scope immediately so scoped resources
+          // (DB pools, caches) are released — otherwise every failed
+          // initialization leaks until the process exits.
+          const effectContext = yield* Effect.gen(function* () {
+            const layer = yield* plugin
+              .initialize({ variables: _variables, secrets: hydratedConfig.secrets }, plugins ?? {})
               .pipe(
                 Effect.provideService(PluginIdTag, plugin.id),
                 Effect.provideService(Scope.Scope, scope),
-                Effect.tapError(() =>
-                  Scope.close(scope, Exit.succeed(undefined)).pipe(
-                    Effect.catchAll((closeError) =>
+              );
+
+            return yield* Layer.buildWithScope(layer, scope).pipe(
+              Effect.provideService(PluginIdTag, plugin.id),
+              Effect.provideService(Scope.Scope, scope),
+              Effect.mapError((error) =>
+                toPluginRuntimeError(error, plugin.id, undefined, "initialize-layer"),
+              ),
+            );
+          }).pipe(
+            Effect.onExit((exit) =>
+              Exit.isSuccess(exit)
+                ? Effect.void
+                : Scope.close(scope, exit).pipe(
+                    Effect.catchCause((closeCause) =>
                       Effect.logWarning(
                         `Failed to close scope for plugin ${plugin.id} after initialize error`,
-                        closeError,
+                        closeCause,
                       ),
                     ),
                   ),
-                ),
-                Effect.tapError((error) =>
-                  Effect.logError(`Plugin ${plugin.id} failed during initialize-plugin: ${error}`),
-                ),
-                Effect.mapError((error) =>
-                  toPluginRuntimeError(error, plugin.id, undefined, "initialize-plugin", false),
-                ),
-              );
+            ),
+            Effect.tapError((error) =>
+              Effect.logError(
+                `Plugin ${plugin.id} failed during initialize-plugin: ${String(error)}`,
+              ),
+            ),
+            Effect.mapError((error) =>
+              toPluginRuntimeError(error, plugin.id, undefined, "initialize-plugin"),
+            ),
+          );
 
-            return {
-              plugin,
-              metadata: pluginInstance.metadata,
-              config: { variables: _variables, secrets: hydratedConfig.secrets },
-              context,
-              scope,
-            } satisfies InitializedPlugin<T>;
-          }),
-      };
-    }),
-  },
-) {}
+          return {
+            plugin,
+            metadata: pluginInstance.metadata,
+            config: { variables: _variables, secrets: hydratedConfig.secrets },
+            effectContext,
+            scope,
+            warnings: collectPluginWarnings(plugin, {
+              variables: _variables,
+              secrets: hydratedConfig.secrets,
+            }),
+          } satisfies InitializedPlugin<T>;
+        }),
+    };
+  }),
+);

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

@@ -1,23 +1,48 @@
-import { Effect, Exit, Layer, Scope } from "effect";
+import { Context, Effect, Exit, Layer, Scope } from "effect";
 import type {
   AnyPlugin,
   AnyPluginConstructor,
   InitializedPlugin,
+  LoadedPlugin,
+  PluginInstance,
   PluginRegistry,
   SecretsConfig,
 } from "../../types";
-import { ModuleFederationService } from "./module-federation.service";
-import { PluginLifecycleService } from "./plugin-lifecycle.service";
+import type { PluginRuntimeError } from "../errors";
+import { ModuleFederationServiceDefault } from "./module-federation.service";
+import { PluginLifecycleService, PluginLifecycleServiceDefault } from "./plugin-lifecycle.service";
 import {
   PluginLoaderService,
+  PluginLoaderServiceDefault,
   PluginMapTag,
   PluginRegistryTag,
-  RegistryService,
+  RegistryServiceDefault,
 } from "./plugin-loader.service";
-import { SecretsConfigTag, SecretsService } from "./secrets.service";
+import { SecretsConfigTag, SecretsServiceDefault } from "./secrets.service";
 
-export class PluginService extends Effect.Service<PluginService>()("PluginService", {
-  scoped: Effect.gen(function* () {
+export interface PluginServiceShape {
+  loadPlugin: (pluginId: string) => Effect.Effect<LoadedPlugin, PluginRuntimeError>;
+  instantiatePlugin: <T extends AnyPlugin>(
+    pluginId: string,
+    loadedPlugin: LoadedPlugin<T>,
+  ) => Effect.Effect<PluginInstance<T>, PluginRuntimeError>;
+  initializePlugin: <T extends AnyPlugin>(
+    pluginInstance: PluginInstance<T>,
+    config: any,
+    plugins?: Record<string, unknown>,
+  ) => Effect.Effect<InitializedPlugin<T>, PluginRuntimeError>;
+  registerPlugin: (plugin: InitializedPlugin<AnyPlugin>) => Effect.Effect<void>;
+  shutdownPlugin: (plugin: InitializedPlugin<AnyPlugin>) => Effect.Effect<void>;
+  cleanup: Effect.Effect<void>;
+}
+
+export class PluginService extends Context.Service<PluginService, PluginServiceShape>()(
+  "PluginService",
+) {}
+
+export const PluginServiceDefault = Layer.effect(
+  PluginService,
+  Effect.gen(function* () {
     const loader = yield* PluginLoaderService;
     const lifecycle = yield* PluginLifecycleService;
 
@@ -27,44 +52,37 @@ export class PluginService extends Effect.Service<PluginService>()("PluginServic
       initializePlugin: loader.initializePlugin,
       registerPlugin: (plugin: InitializedPlugin<AnyPlugin>) => lifecycle.register(plugin),
       shutdownPlugin: (plugin: InitializedPlugin<AnyPlugin>) =>
-        Effect.gen(function* () {
-          yield* plugin.plugin
-            .shutdown()
-            .pipe(
-              Effect.catchAll((error) =>
-                Effect.logWarning(`Failed to shutdown plugin ${plugin.plugin.id}`, error),
-              ),
-            );
-
-          yield* Scope.close(plugin.scope, Exit.succeed(undefined));
-
-          yield* lifecycle.unregister(plugin);
-        }),
+        Scope.close(plugin.scope, Exit.succeed(undefined)).pipe(
+          Effect.catchCause((cause) =>
+            Effect.logWarning(`Failed to shutdown plugin ${plugin.plugin.id}`, cause),
+          ),
+          Effect.ensuring(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));
+export const PluginServiceLive = (
+  registry: PluginRegistry,
+  secrets: SecretsConfig,
+  pluginMap: Record<string, AnyPluginConstructor> = {},
+) => {
+  const contextLayer = Layer.mergeAll(
+    Layer.succeed(PluginRegistryTag, registry),
+    Layer.succeed(SecretsConfigTag, secrets),
+    Layer.succeed(PluginMapTag, pluginMap),
+  );
 
-    return PluginService.Default.pipe(
-      Layer.provide(PluginLoaderService.Default),
-      Layer.provide(servicesLayer),
-    );
-  };
-}
+  const servicesLayer = Layer.mergeAll(
+    ModuleFederationServiceDefault,
+    SecretsServiceDefault,
+    RegistryServiceDefault,
+    PluginLifecycleServiceDefault,
+  ).pipe(Layer.provide(contextLayer));
+
+  return PluginServiceDefault.pipe(
+    Layer.provide(PluginLoaderServiceDefault),
+    Layer.provide(servicesLayer),
+  );
+};