every-plugin 0.8.9 → 2.2.2

package/src/runtime/errors.ts

@@ -0,0 +1,332 @@
+import { ORPCError } from "@orpc/contract";
+import { Cause, Data } from "effect";
+import type { z } from "zod";
+
+export class PluginRuntimeError extends Data.TaggedError("PluginRuntimeError")<{
+  readonly pluginId?: string;
+  readonly operation?: string;
+  readonly procedureName?: string;
+  readonly cause?: Error;
+  readonly retryable: boolean;
+}> {}
+
+export class ModuleFederationError extends Data.TaggedError("ModuleFederationError")<{
+  readonly pluginId: string;
+  readonly remoteUrl: string;
+  readonly cause?: Error;
+}> {}
+
+export class ValidationError extends Data.TaggedError("ValidationError")<{
+  readonly pluginId: string;
+  readonly stage: "config" | "input" | "output" | "state";
+  readonly zodError: z.ZodError;
+}> {}
+
+const extractErrorMessage = (error: unknown): string => {
+  if (!error) return "Unknown error";
+
+  if (error instanceof Error) {
+    if (error.message) return error.message;
+    if ((error as any).cause instanceof Error) {
+      return extractErrorMessage((error as any).cause);
+    }
+  }
+
+  if (error instanceof AggregateError && error.errors?.length) {
+    return error.errors.map((e) => extractErrorMessage(e)).join("; ");
+  }
+
+  if (typeof error === "object" && "message" in error) {
+    return String((error as any).message);
+  }
+
+  return String(error);
+};
+
+const formatValidationIssue = (issue: any, index: number, maxDisplay: number): string => {
+  if (index >= maxDisplay) return "";
+
+  const path =
+    Array.isArray(issue.path) && issue.path.length > 0
+      ? issue.path.join(".")
+      : issue.path || "root";
+
+  const message = issue.message || "Validation failed";
+
+  return `│    ${index + 1}. ${path}: ${message}`;
+};
+
+const formatDataPreview = (data: unknown, maxLength = 100): string => {
+  if (!data) return "undefined";
+
+  try {
+    const str = JSON.stringify(data);
+    if (str.length <= maxLength) return str;
+
+    if (typeof data === "object" && data !== null) {
+      if (Array.isArray(data)) {
+        return `Array(${data.length}) [...]`;
+      }
+      const keys = Object.keys(data);
+      return `{ ${keys.slice(0, 3).join(", ")}${keys.length > 3 ? ", ..." : ""} }`;
+    }
+
+    return `${str.slice(0, maxLength)}...`;
+  } catch {
+    return String(data).slice(0, maxLength);
+  }
+};
+
+const formatORPCValidationError = (error: any): string[] | null => {
+  const cause = error?.cause || error;
+
+  if (!cause?.issues || !Array.isArray(cause.issues) || cause.issues.length === 0) {
+    return null;
+  }
+
+  const lines: string[] = [];
+  const errorType = error?.message || cause?.message || "Validation failed";
+
+  lines.push(`\n╭─ oRPC Validation Error ${"─".repeat(30)}`);
+  lines.push(`│  ${errorType}`);
+  lines.push(`│`);
+
+  const maxDisplay = 10;
+  const totalIssues = cause.issues.length;
+
+  lines.push(`│  Issues (${totalIssues}):`);
+
+  const displayedIssues = cause.issues.slice(0, maxDisplay);
+  displayedIssues.forEach((issue: any, idx: number) => {
+    const formatted = formatValidationIssue(issue, idx, maxDisplay);
+    if (formatted) lines.push(formatted);
+  });
+
+  if (totalIssues > maxDisplay) {
+    lines.push(`│    ... and ${totalIssues - maxDisplay} more`);
+  }
+
+  if (cause.data !== undefined) {
+    lines.push(`│`);
+    lines.push(`│  Data preview: ${formatDataPreview(cause.data, 80)}`);
+  }
+
+  lines.push(`╰${"─".repeat(50)}\n`);
+
+  return lines;
+};
+
+export const formatORPCError = (error: any): void => {
+  if (!(error instanceof ORPCError)) {
+    return;
+  }
+
+  const validationLines = formatORPCValidationError(error);
+  if (validationLines) {
+    console.error(validationLines.join("\n"));
+    return;
+  }
+
+  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)}`);
+  lines.push(`│  ${message}`);
+  lines.push(`│  Code: ${code} (${status})`);
+  lines.push(`│`);
+
+  if (error.data) {
+    const dataType = typeof error.data;
+    if (dataType === "object" && error.data !== null) {
+      if ("retryAfter" in error.data) {
+        lines.push(`│  Retry after: ${error.data.retryAfter} seconds`);
+      }
+      if ("remainingRequests" in error.data) {
+        lines.push(`│  Remaining: ${error.data.remainingRequests} requests`);
+      }
+      if ("host" in error.data) {
+        lines.push(`│  Host: ${error.data.host}`);
+      }
+      if ("port" in error.data) {
+        lines.push(`│  Port: ${error.data.port}`);
+      }
+      if ("suggestion" in error.data) {
+        lines.push(`│  → ${error.data.suggestion}`);
+      }
+      if ("resource" in error.data) {
+        lines.push(`│  Resource: ${error.data.resource}`);
+      }
+      if ("resourceId" in error.data) {
+        lines.push(`│  ID: ${error.data.resourceId}`);
+      }
+    }
+  }
+
+  switch (code) {
+    case "UNAUTHORIZED":
+      lines.push(`│  → Check your API key or credentials`);
+      break;
+    case "TOO_MANY_REQUESTS":
+      lines.push(`│  → Wait before retrying`);
+      break;
+    case "SERVICE_UNAVAILABLE":
+    case "BAD_GATEWAY":
+    case "GATEWAY_TIMEOUT":
+      lines.push(`│  → The service may be temporarily unavailable`);
+      break;
+    case "TIMEOUT":
+      lines.push(`│  → The operation took too long`);
+      break;
+  }
+
+  lines.push(`╰${"─".repeat(50)}\n`);
+  console.error(lines.join("\n"));
+};
+
+const formatPluginError = (
+  pluginId: string | undefined,
+  operation: string | undefined,
+  message: string,
+): void => {
+  const lines: string[] = [];
+
+  lines.push(`\n╭─ Plugin Error ${"─".repeat(40)}`);
+  if (pluginId) lines.push(`│  Plugin: ${pluginId}`);
+  if (operation) lines.push(`│  During: ${operation}`);
+  lines.push(`│`);
+
+  if (message.includes("ECONNREFUSED")) {
+    lines.push(`│  ❌ Connection refused`);
+    lines.push(`│  `);
+    lines.push(`│  A required service is not running.`);
+    lines.push(`│  → Run: docker compose up -d`);
+  } else if (message.includes("ENOTFOUND")) {
+    lines.push(`│  ❌ Host not found`);
+    lines.push(`│  `);
+    lines.push(`│  Check your connection URL or network settings.`);
+  } else if (message.includes("ETIMEDOUT") || message.includes("timeout")) {
+    lines.push(`│  ❌ Connection timeout`);
+    lines.push(`│  `);
+    lines.push(`│  The service took too long to respond.`);
+  } else if (message.includes("EACCES") || message.includes("permission")) {
+    lines.push(`│  ❌ Permission denied`);
+    lines.push(`│  `);
+    lines.push(`│  Check credentials or access permissions.`);
+  } else if (message.includes("401") || message.includes("unauthorized")) {
+    lines.push(`│  ❌ Authentication failed`);
+    lines.push(`│  `);
+    lines.push(`│  Check your API key or credentials.`);
+  } else {
+    lines.push(`│  ❌ ${message}`);
+  }
+
+  lines.push(`╰${"─".repeat(50)}\n`);
+
+  console.error(lines.join("\n"));
+};
+
+const isRetryableError = (message: string): boolean => {
+  const retryablePatterns = ["ETIMEDOUT", "ECONNRESET", "timeout", "503", "429"];
+  return retryablePatterns.some((p) => message.toLowerCase().includes(p.toLowerCase()));
+};
+
+// 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;
+  }
+};
+
+// Convert ORPC errors from plugin procedures to PluginRuntimeError
+export const wrapORPCError = (
+  orpcError: ORPCError<string, unknown>,
+  pluginId?: string,
+  procedureName?: string,
+  operation?: string,
+): PluginRuntimeError => {
+  const validationLines = formatORPCValidationError(orpcError);
+  if (validationLines) {
+    console.error(validationLines.join("\n"));
+  }
+
+  return new PluginRuntimeError({
+    pluginId,
+    operation,
+    procedureName,
+    retryable: isRetryableORPCCode(orpcError.code),
+    cause: orpcError as Error,
+  });
+};
+
+/**
+ * Extracts the underlying error from Effect's FiberFailure wrapper.
+ * When Effect.runPromise rejects, errors are wrapped in FiberFailure.
+ * This extracts the original error so oRPC can handle it properly.
+ */
+export const extractFromFiberFailure = (error: unknown): unknown => {
+  if (!error || typeof error !== "object") return error;
+
+  if ("cause" in error) {
+    const cause = (error as { cause?: unknown }).cause;
+
+    if (cause && typeof cause === "object" && "_tag" in cause) {
+      try {
+        const squashed = Cause.squash(cause as Cause.Cause<unknown>);
+        if (squashed instanceof ORPCError) {
+          return squashed;
+        }
+        return squashed;
+      } catch {
+        // Not a valid Cause
+      }
+    }
+
+    if (cause instanceof ORPCError) {
+      return cause;
+    }
+  }
+
+  return error;
+};
+
+// Universal error converter for the runtime
+export const toPluginRuntimeError = (
+  error: unknown,
+  pluginId?: string,
+  procedureName?: string,
+  operation?: string,
+  defaultRetryable = false,
+): PluginRuntimeError => {
+  if (error instanceof ORPCError) {
+    return wrapORPCError(error, pluginId, procedureName, operation);
+  }
+
+  if (error instanceof PluginRuntimeError) {
+    return error;
+  }
+
+  const validationLines = formatORPCValidationError(error);
+  if (validationLines) {
+    console.error(validationLines.join("\n"));
+  } else {
+    const message = extractErrorMessage(error);
+    formatPluginError(pluginId, operation, message);
+  }
+
+  return new PluginRuntimeError({
+    pluginId,
+    operation,
+    procedureName,
+    retryable: defaultRetryable || isRetryableError(extractErrorMessage(error)),
+    cause: error instanceof Error ? error : new Error(extractErrorMessage(error)),
+  });
+};

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;