every-plugin 2.10.0 → 3.0.0-rc.0

package/src/runtime/errors.ts

@@ -1,4 +1,4 @@
-import { ORPCError } from "@orpc/contract";
+import { ORPCError } from "@orpc/server";
 import { Cause, Data } from "effect";
 import type { z } from "zod";
 
@@ -7,8 +7,11 @@ export class PluginRuntimeError extends Data.TaggedError("PluginRuntimeError")<{
   readonly operation?: string;
   readonly procedureName?: string;
   readonly cause?: Error;
-  readonly retryable: boolean;
-}> {}
+}> {
+  override get message() {
+    return this.cause?.message ?? "Plugin operation failed";
+  }
+}
 
 export class ModuleFederationError extends Data.TaggedError("ModuleFederationError")<{
   readonly pluginId: string;
@@ -22,6 +25,22 @@ export class ValidationError extends Data.TaggedError("ValidationError")<{
   readonly zodError: z.ZodError;
 }> {}
 
+const stringifyUnknown = (value: unknown): string => {
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  if (value instanceof Error) return value.message;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+    return `${value}`;
+  }
+  if (typeof value === "symbol") return value.description ?? "";
+  try {
+    return JSON.stringify(value) ?? "[Unserializable value]";
+  } catch {
+    return "[Unserializable value]";
+  }
+};
+
 const extractErrorMessage = (error: unknown): string => {
   if (!error) return "Unknown error";
 
@@ -40,7 +59,26 @@ const extractErrorMessage = (error: unknown): string => {
     return String((error as any).message);
   }
 
-  return String(error);
+  return stringifyUnknown(error);
+};
+
+/**
+ * The deepest Error along the cause chain — the original throw site. Wrapper
+ * errors (PluginRuntimeError, ModuleFederationError) carry their own stacks
+ * (the wrapping frames); diagnosis needs the cause's stack (the actual
+ * failing module inside the evaluated remote entry).
+ */
+export const deepestErrorStack = (error: unknown): string | undefined => {
+  let current = error;
+  let deepest: string | undefined;
+  let hops = 0;
+  while (current instanceof Error && hops < 8) {
+    if (current.stack) deepest = current.stack;
+    current = (current as { cause?: unknown }).cause as unknown;
+    hops += 1;
+  }
+  if (current instanceof Error && current.stack) deepest = current.stack;
+  return deepest;
 };
 
 const formatValidationIssue = (issue: any, index: number, maxDisplay: number): string => {
@@ -73,7 +111,7 @@ const formatDataPreview = (data: unknown, maxLength = 100): string => {
 
     return `${str.slice(0, maxLength)}...`;
   } catch {
-    return String(data).slice(0, maxLength);
+    return stringifyUnknown(data).slice(0, maxLength);
   }
 };
 
@@ -116,9 +154,31 @@ const formatORPCValidationError = (error: any): string[] | null => {
   return lines;
 };
 
+const formatUnknownError = (error: any): string | null => {
+  if (!error) return null;
+  const message = extractErrorMessage(error);
+  const lines: string[] = [];
+  lines.push(`\n╭─ Unhandled error ${"─".repeat(37)}`);
+  for (const line of message.split("\n")) {
+    lines.push(`│  ${line}`);
+  }
+  const stack = error instanceof Error ? error.stack?.split("\n").slice(1, 6) : undefined;
+  if (stack && stack.length > 0) {
+    lines.push(`│`);
+    for (const line of stack) {
+      lines.push(`│  ${line.trim()}`);
+    }
+  }
+  lines.push(`╰${"─".repeat(50)}\n`);
+  return lines.join("\n");
+};
+
 export const formatORPCError = (error: any): string | null => {
   if (!(error instanceof ORPCError)) {
-    return null;
+    // Unknown errors used to return null, leaving internal failures (e.g. a
+    // storage backend throw) invisible in host logs while oRPC serialized
+    // them client-side as a bare INTERNAL_SERVER_ERROR.
+    return formatUnknownError(error);
   }
 
   const validationLines = formatORPCValidationError(error);
@@ -128,7 +188,6 @@ export const formatORPCError = (error: any): string | null => {
 
   const lines: string[] = [];
   const code = error.code || "UNKNOWN";
-  const status = error.status || 500;
   const message = error.message || "An error occurred";
 
   lines.push(`\n╭─ oRPC Error ${"─".repeat(40)}`);
@@ -136,7 +195,7 @@ export const formatORPCError = (error: any): string | null => {
   for (const line of messageLines) {
     lines.push(`│  ${line}`);
   }
-  lines.push(`│  Code: ${code} (${status})`);
+  lines.push(`│  Code: ${code}`);
   lines.push(`│`);
 
   if (error.data) {
@@ -187,23 +246,126 @@ export const formatORPCError = (error: any): string | null => {
   return lines.join("\n");
 };
 
-const isRetryableError = (message: string): boolean => {
-  const retryablePatterns = ["ETIMEDOUT", "ECONNRESET", "timeout", "503", "429"];
-  return retryablePatterns.some((p) => message.toLowerCase().includes(p.toLowerCase()));
-};
+export type PluginFailureKind =
+  | "mf"
+  | "integrity"
+  | "config"
+  | "validation"
+  | "network"
+  | "unknown";
+
+export interface PluginFailureClassification {
+  kind: PluginFailureKind;
+  retryable: boolean;
+  message: string;
+  suggestion?: string;
+}
 
-// Helper to determine if an oRPC error code is retryable
-export const isRetryableORPCCode = (code: string): boolean => {
-  switch (code) {
-    case "TOO_MANY_REQUESTS":
-    case "SERVICE_UNAVAILABLE":
-    case "BAD_GATEWAY":
-    case "GATEWAY_TIMEOUT":
-    case "TIMEOUT":
-      return true;
-    default:
-      return false;
+/**
+ * Structured report of one plugin-load failure, built by a loader (the host's
+ * plugin boot, the dev server) from a `PluginFailureClassification` plus
+ * loader context. This is the shape health endpoints and dashboards consume —
+ * keep it serializable.
+ */
+export interface PluginLoadFailureInfo {
+  /** loader-side key (host entry key, dev plugin id) */
+  pluginKey: string;
+  pluginUrl?: string;
+  /** failing runtime stage when the cause is stage-attributed */
+  operation?: string;
+  kind: string;
+  retryable: boolean;
+  message: string;
+  suggestion?: string;
+  /** loader context: which env secret the plugin's DB binding expects */
+  dbSecret?: string;
+  dbUrlMasked?: string;
+}
+
+const NETWORK_RETRYABLE_PATTERNS = ["ETIMEDOUT", "ECONNRESET", "timeout", "503", "429"] as const;
+const NETWORK_DEAD_PATTERNS = ["ECONNREFUSED", "ENOTFOUND", "EHOSTUNREACH"] as const;
+const RETRYABLE_ORPC_CODES = new Set([
+  "TOO_MANY_REQUESTS",
+  "SERVICE_UNAVAILABLE",
+  "BAD_GATEWAY",
+  "GATEWAY_TIMEOUT",
+  "TIMEOUT",
+]);
+
+/**
+ * One classification for plugin lifecycle failures across MF / validation /
+ * network sources. This is the recovery policy — nothing in the runtime
+ * retries on it today by design (the host degrades and runs without a failed
+ * plugin); consumers (host bootstrap messages, the dev server retry loop)
+ * read kind / retryable / suggestion to decide what to tell the author.
+ */
+export const classifyPluginFailure = (error: unknown): PluginFailureClassification => {
+  let current: unknown = extractFromFiberFailure(error);
+  let hops = 0;
+  while (current && typeof current === "object" && hops < 8) {
+    if (current instanceof ModuleFederationError) {
+      return {
+        kind: "mf",
+        retryable: false,
+        message: extractErrorMessage(current),
+        suggestion:
+          "Run bos mf check — the deployed plugin bundle is likely stale (sharedDep / pluginVersion skew), then redeploy the plugin and bos publish --deploy --packages local",
+      };
+    }
+    if (current instanceof ValidationError) {
+      return {
+        kind: "validation",
+        retryable: false,
+        message: `${current.stage}: ${extractErrorMessage(current.zodError)}`,
+        suggestion: `Fix the plugin's ${current.stage} schema at plugins/${current.pluginId}`,
+      };
+    }
+    if (current instanceof ORPCError) {
+      const retryableByCode = RETRYABLE_ORPC_CODES.has(current.code);
+      return {
+        kind: "network",
+        retryable: retryableByCode,
+        message: current.message,
+        suggestion: retryableByCode
+          ? "The plugin procedure failed transiently — retry the call"
+          : undefined,
+      };
+    }
+    current = (current as { cause?: unknown }).cause;
+    hops += 1;
   }
+
+  const message = extractErrorMessage(error);
+  const lower = message.toLowerCase();
+
+  if (NETWORK_RETRYABLE_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) {
+    return {
+      kind: "network",
+      retryable: true,
+      message,
+      suggestion: "The remote may be temporarily unavailable — retry after redeploying the plugin",
+    };
+  }
+  if (NETWORK_DEAD_PATTERNS.some((p) => lower.includes(p.toLowerCase()))) {
+    return {
+      kind: "network",
+      retryable: false,
+      message,
+      suggestion:
+        "The plugin host is unreachable — check plugins.<id> entry URLs in bos.config.json",
+    };
+  }
+  if (lower.includes("integrity") || lower.includes("sri")) {
+    return {
+      kind: "integrity",
+      retryable: true,
+      message,
+      suggestion:
+        "The deployed bundle content does not match its recorded integrity — redeploy the plugin so bos.config.json is republished with a fresh hash",
+    };
+  }
+
+  return { kind: "unknown", retryable: false, message };
 };
 
 // Convert ORPC errors from plugin procedures to PluginRuntimeError
@@ -217,7 +379,6 @@ export const wrapORPCError = (
     pluginId,
     operation,
     procedureName,
-    retryable: isRetryableORPCCode(orpcError.code),
     cause: orpcError as Error,
   });
 };
@@ -235,7 +396,7 @@ export const extractFromFiberFailure = (error: unknown): unknown => {
 
     if (cause && typeof cause === "object" && "_tag" in cause) {
       try {
-        const squashed = Cause.squash(cause as Cause.Cause<unknown>);
+        const squashed = Cause.squash(cause as unknown as Cause.Cause<unknown>);
         if (squashed instanceof ORPCError) {
           return squashed;
         }
@@ -259,7 +420,6 @@ export const toPluginRuntimeError = (
   pluginId?: string,
   procedureName?: string,
   operation?: string,
-  defaultRetryable = false,
 ): PluginRuntimeError => {
   if (error instanceof ORPCError) {
     return wrapORPCError(error, pluginId, procedureName, operation);
@@ -273,7 +433,6 @@ export const toPluginRuntimeError = (
     pluginId,
     operation,
     procedureName,
-    retryable: defaultRetryable || isRetryableError(extractErrorMessage(error)),
     cause: error instanceof Error ? error : new Error(extractErrorMessage(error)),
   });
 };

package/src/runtime/index.ts

@@ -1,5 +1,9 @@
+import "@orpc/experimental-effect/extensions/effect";
+import "@orpc/openapi/extensions/route";
+
 import { createRouterClient } from "@orpc/server";
-import { Cause, Effect, Exit, Hash, ManagedRuntime, Option } from "effect";
+import { Cause, Effect, Exit, ManagedRuntime, Option } from "effect";
+import { DEV_ENTRY_FILENAME } from "../build/artifact-names";
 import type {
   AnyPlugin,
   AnyPluginConstructor,
@@ -16,25 +20,94 @@ import type {
   RegisteredPlugins,
   UsePluginResult,
 } from "../types";
-import { PluginRuntimeError } from "./errors";
-import { PluginService } from "./services/plugin.service";
+import { PluginRuntimeError, toPluginRuntimeError } from "./errors";
+import { PluginService, PluginServiceLive } from "./services/plugin.service";
+
+const MAX_CACHE_KEY_DEPTH = 32;
 
 export class PluginRuntime<R = RegisteredPlugins> {
   readonly __registryType?: R;
 
-  private pluginCache = new Map<
-    string,
-    Effect.Effect<InitializedPlugin<AnyPlugin>, PluginRuntimeError>
-  >();
+  private pluginCache = new Map<string, Promise<InitializedPlugin<AnyPlugin>>>();
+  private routerCache = new Map<string, PluginRouterType<any>>();
+  private cacheLeafIds = new WeakMap<object, number>();
+  private nextCacheLeafId = 0;
 
   constructor(
     private runtime: ManagedRuntime.ManagedRuntime<PluginService, never>,
     private registry: PluginRegistry,
   ) {}
 
+  /**
+   * Cache key for plugin instances: JSON-equal configs share one plugin
+   * instance (variables and secrets originate from bos.config.json, so they
+   * are JSON values). Values outside the JSON domain follow Effect's Hash
+   * semantics — symbols key by description, functions and class instances by
+   * reference identity — and the host creates its pluginsClient map once per
+   * boot, making identity the correct equivalence for function-bearing
+   * configs.
+   */
   private generateCacheKey(pluginId: string, config: unknown): string {
-    const configHash = Hash.structure(config as object).toString();
-    return `${pluginId}:${configHash}`;
+    return `${pluginId}:${this.canonicalizeConfig(config, 0, new Set())}`;
+  }
+
+  private canonicalizeConfig(value: unknown, depth: number, ancestors: Set<object>): string {
+    switch (typeof value) {
+      case "undefined":
+        return "undefined";
+      case "string":
+        return `string:${JSON.stringify(value)}`;
+      case "number":
+        return `number:${Object.is(value, -0) ? "-0" : String(value)}`;
+      case "bigint":
+        return `bigint:${value.toString()}`;
+      case "boolean":
+        return `boolean:${value}`;
+      case "symbol":
+        return `symbol:${String(value)}`;
+      case "function":
+        return `ref:${this.getCacheLeafId(value)}`;
+      case "object": {
+        if (value === null) return "null";
+        if (ancestors.has(value) || depth >= MAX_CACHE_KEY_DEPTH) {
+          return `ref:${this.getCacheLeafId(value)}`;
+        }
+
+        if (Array.isArray(value)) {
+          ancestors.add(value);
+          const serialized = `[${value
+            .map((item) => this.canonicalizeConfig(item, depth + 1, ancestors))
+            .join(",")}]`;
+          ancestors.delete(value);
+          return serialized;
+        }
+
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+          return `ref:${this.getCacheLeafId(value)}`;
+        }
+
+        const record = value as Record<string, unknown>;
+        ancestors.add(value);
+        const serialized = `{${Object.keys(record)
+          .sort()
+          .map(
+            (key) =>
+              `${JSON.stringify(key)}:${this.canonicalizeConfig(record[key], depth + 1, ancestors)}`,
+          )
+          .join(",")}}`;
+        ancestors.delete(value);
+        return serialized;
+      }
+    }
+  }
+
+  private getCacheLeafId(value: object): number {
+    const existing = this.cacheLeafIds.get(value);
+    if (existing !== undefined) return existing;
+    const id = this.nextCacheLeafId++;
+    this.cacheLeafIds.set(value, id);
+    return id;
   }
 
   private validatePluginId(pluginId: string): Effect.Effect<string, PluginRuntimeError> {
@@ -44,7 +117,6 @@ export class PluginRuntime<R = RegisteredPlugins> {
           pluginId: String(pluginId),
           operation: "validate-plugin-id",
           cause: new Error(`Plugin ID '${String(pluginId)}' not found in registry.`),
-          retryable: false,
         }),
       );
     }
@@ -55,7 +127,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
     const exit = await this.runtime.runPromiseExit(effect);
 
     if (Exit.isFailure(exit)) {
-      const error = Cause.failureOption(exit.cause);
+      const error = Cause.findErrorOption(exit.cause);
       if (Option.isSome(error)) {
         throw error.value;
       }
@@ -74,7 +146,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
 
     let cachedPlugin = this.pluginCache.get(cacheKey);
     if (!cachedPlugin) {
-      const operation = Effect.gen(this, function* () {
+      const operation = Effect.gen({ self: this }, function* () {
         const pluginService = yield* PluginService;
         const validatedId = yield* this.validatePluginId(pluginId);
 
@@ -85,27 +157,45 @@ export class PluginRuntime<R = RegisteredPlugins> {
         yield* pluginService.registerPlugin(initialized);
 
         return initialized;
-      }).pipe(Effect.annotateLogs({ plugin: pluginId }), Effect.provide(this.runtime));
+      });
 
-      cachedPlugin = Effect.cached(operation).pipe(Effect.flatten);
+      cachedPlugin = this.runPromise(operation);
       this.pluginCache.set(cacheKey, cachedPlugin);
     }
 
     let initialized: InitializedPlugin<AnyPlugin>;
     try {
-      initialized = await this.runPromise(cachedPlugin);
+      initialized = await cachedPlugin;
     } catch (error) {
-      // Evict failed initializations so the next call retries instead
-      // of returning the permanently-cached failure from Effect.cached.
-      this.pluginCache.delete(cacheKey);
+      if (this.pluginCache.get(cacheKey) === cachedPlugin) {
+        this.pluginCache.delete(cacheKey);
+        this.routerCache.delete(cacheKey);
+      }
       throw error;
     }
 
     // Construct the router once per plugin instance, not per client/request.
-    const router = initialized.plugin.createRouter(initialized.context) as PluginRouterType<R[K]>;
+    let router = this.routerCache.get(cacheKey);
+    if (!router) {
+      try {
+        router = initialized.plugin.createRouter(plugins ?? {}) as PluginRouterType<R[K]>;
+        this.routerCache.set(cacheKey, router);
+      } catch (error) {
+        await this.evictPlugin(pluginId, config, plugins);
+        throw error;
+      }
+    }
 
-    // Create client factory that accepts request context
-    const createClient = (context?: any) => createRouterClient(router, { context: context ?? {} });
+    // Create client factory that accepts request context. The plugin's
+    // Effect context is injected so `.effect()` handlers resolve services
+    // on in-process (server-side / SSR) calls.
+    const createClient = (context?: any) =>
+      createRouterClient(router, {
+        context: {
+          ...context,
+          "effect/context": initialized.effectContext,
+        },
+      });
 
     return {
       createClient: createClient as any,
@@ -121,7 +211,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
     const effect = Effect.gen(function* () {
       const pluginService = yield* PluginService;
       return yield* pluginService.loadPlugin(pluginId);
-    }).pipe(Effect.annotateLogs({ plugin: pluginId }));
+    });
     return this.runPromise(effect) as Promise<LoadedPlugin<RegisteredPlugin<K, R>>>;
   }
 
@@ -132,7 +222,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
     const effect = Effect.gen(function* () {
       const pluginService = yield* PluginService;
       return yield* pluginService.instantiatePlugin(pluginId, loadedPlugin);
-    }).pipe(Effect.annotateLogs({ plugin: pluginId }));
+    });
     return this.runPromise(effect) as Promise<PluginInstance<RegisteredPlugin<K, R>>>;
   }
 
@@ -146,17 +236,22 @@ export class PluginRuntime<R = RegisteredPlugins> {
       const initialized = yield* pluginService.initializePlugin(instance, config, plugins);
       yield* pluginService.registerPlugin(initialized);
       return initialized;
-    }).pipe(Effect.annotateLogs({ plugin: instance.plugin.id }));
+    });
     return this.runPromise(effect);
   }
 
   async shutdown(): Promise<void> {
     const effect = Effect.gen(function* () {
       const pluginService = yield* PluginService;
-      yield* pluginService.cleanup();
+      yield* pluginService.cleanup;
     });
-    await this.runPromise(effect);
-    await this.runtime.dispose();
+    try {
+      await this.runPromise(effect);
+    } finally {
+      this.pluginCache.clear();
+      this.routerCache.clear();
+      await this.runtime.dispose();
+    }
   }
 
   async evictPlugin<K extends keyof R & string>(
@@ -166,30 +261,24 @@ export class PluginRuntime<R = RegisteredPlugins> {
   ): Promise<void> {
     const cacheKey = this.generateCacheKey(pluginId, { ...config, __plugins: plugins ?? {} });
 
-    const effect = Effect.gen(this, function* () {
+    const effect = Effect.gen({ self: this }, function* () {
       const pluginService = yield* PluginService;
       const cachedPlugin = this.pluginCache.get(cacheKey);
 
       if (cachedPlugin) {
         this.pluginCache.delete(cacheKey);
+        this.routerCache.delete(cacheKey);
 
-        const pluginResult = yield* cachedPlugin.pipe(Effect.catchAll(() => Effect.succeed(null)));
+        const pluginResult = yield* Effect.tryPromise({
+          try: () => cachedPlugin,
+          catch: (error) => toPluginRuntimeError(error, pluginId, undefined, "evict-plugin"),
+        }).pipe(Effect.orElseSucceed(() => null));
 
         if (pluginResult) {
-          yield* pluginService
-            .shutdownPlugin(pluginResult)
-            .pipe(
-              Effect.catchAll((error) =>
-                Effect.logWarning(`Failed to shutdown evicted plugin ${pluginId}`, error),
-              ),
-            );
+          yield* pluginService.shutdownPlugin(pluginResult);
         }
       }
-    }).pipe(
-      Effect.catchAll((error) =>
-        Effect.logWarning(`Plugin eviction failed for ${pluginId}`, error),
-      ),
-    );
+    });
 
     return this.runPromise(effect);
   }
@@ -202,7 +291,7 @@ export class PluginRuntime<R = RegisteredPlugins> {
 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`;
+  return `${url.endsWith("/") ? url.slice(0, -1) : url}/${DEV_ENTRY_FILENAME}`;
 }
 
 /**
@@ -270,7 +359,7 @@ export function createPluginRuntime<TRegistry extends Record<string, PluginRegis
   const normalizedRegistry = normalizeRegistry(config.registry);
   const pluginMap = extractPluginMap(config.registry);
 
-  const layer = PluginService.Live(normalizedRegistry, secrets, pluginMap);
+  const layer = PluginServiceLive(normalizedRegistry, secrets, pluginMap);
   const runtime = ManagedRuntime.make(layer);
 
   return new PluginRuntime(runtime, normalizedRegistry) as PluginRuntime<