every-plugin 3.0.0-rc.0 → 3.0.0-rc.4

package/src/dev/host.ts

@@ -0,0 +1,235 @@
+import type http from "node:http";
+import { createServer } from "node:http";
+
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+  "Access-Control-Allow-Headers": "X-Requested-With, content-type, Authorization",
+};
+
+const applyCorsHeaders = (res: http.ServerResponse) => {
+  Object.entries(corsHeaders).forEach(([key, value]) => {
+    res.setHeader(key, value);
+  });
+};
+
+const sendJson = (res: http.ServerResponse, status: number, body: unknown) => {
+  res.statusCode = status;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(JSON.stringify(body));
+};
+
+const sendText = (res: http.ServerResponse, status: number, text: string) => {
+  res.statusCode = status;
+  res.setHeader("content-type", "text/plain; charset=utf-8");
+  res.end(text);
+};
+
+const pathnameOf = (req: http.IncomingMessage): string =>
+  ((req.url ?? "/").split("?")[0] ?? "/").replace(/\/+$/, "") || "/";
+
+const toWebRequest = (req: http.IncomingMessage, port: number): Request => {
+  const url = `http://localhost:${port}${req.url}`;
+  return new Request(url, {
+    method: req.method,
+    headers: req.headers,
+    body: req.method !== "GET" && req.method !== "HEAD" ? req : undefined,
+    duplex: req.method !== "GET" && req.method !== "HEAD" ? "half" : undefined,
+  } as RequestInit);
+};
+
+const buildHostContext = (
+  effectContext: unknown,
+  webRequest: Request,
+  cachedRawBodyRef: { value: string | null },
+) => {
+  const rawClone =
+    webRequest.method === "GET" || webRequest.method === "HEAD" ? null : webRequest.clone();
+
+  return {
+    reqHeaders: webRequest.headers,
+    "effect/context": effectContext,
+    getRawBody: async (): Promise<string> => {
+      if (cachedRawBodyRef.value !== null) return cachedRawBodyRef.value;
+      if (!rawClone) {
+        cachedRawBodyRef.value = "";
+        return cachedRawBodyRef.value;
+      }
+      cachedRawBodyRef.value = await rawClone.text();
+      return cachedRawBodyRef.value;
+    },
+  };
+};
+
+export interface DirectModuleHostHandler {
+  handle(
+    request: Request,
+    options: { prefix: string; context: unknown },
+  ): Promise<{ response?: Response }>;
+}
+
+const handleOrpc = async (
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  handler: DirectModuleHostHandler,
+  prefix: string,
+  errorLabel: string,
+  effectContext: unknown,
+  port: number,
+) => {
+  try {
+    const webRequest = toWebRequest(req, port);
+    const cachedRawBodyRef = { value: null as string | null };
+    const result = await handler.handle(webRequest, {
+      prefix,
+      context: buildHostContext(effectContext, webRequest, cachedRawBodyRef),
+    });
+
+    if (result.response) {
+      res.statusCode = result.response.status;
+      result.response.headers.forEach((value: string, key: string) => {
+        res.setHeader(key, value);
+      });
+      const text = await result.response.text();
+      if (!res.getHeader("content-length")) {
+        res.setHeader("content-length", Buffer.byteLength(text).toString());
+      }
+      res.end(text);
+    } else {
+      sendText(res, 404, "Not Found");
+    }
+  } catch (error) {
+    console.error(`${errorLabel} error:`, error);
+    sendJson(res, 500, { error: (error as Error).message });
+  }
+};
+
+export interface DirectModuleHostHandlers {
+  rpc: DirectModuleHostHandler | null;
+  api: DirectModuleHostHandler | null;
+}
+
+export interface DirectModuleHostOptions {
+  name: string;
+  handlers: DirectModuleHostHandlers;
+  effectContext: unknown;
+  port?: number;
+  version?: string;
+  rpcPrefix?: `/${string}`;
+  apiPrefix?: `/${string}`;
+  staticHandler?:
+    | ((req: http.IncomingMessage, res: http.ServerResponse, next: () => void) => void)
+    | null;
+}
+
+export interface DirectModuleHostHandle {
+  port: number;
+  close: () => Promise<void>;
+}
+
+export async function startDirectModuleHost(
+  options: DirectModuleHostOptions,
+): Promise<DirectModuleHostHandle> {
+  const port = options.port ?? 0;
+  let resolvedPort = port;
+  const rpcPrefix = options.rpcPrefix ?? "/api/rpc";
+  const apiPrefix = options.apiPrefix ?? "/api";
+  const staticHandler = options.staticHandler ?? null;
+  const resolveEffectContext: () => unknown =
+    typeof options.effectContext === "function"
+      ? (options.effectContext as () => unknown)
+      : () => options.effectContext;
+
+  const server = createServer((req, res) => {
+    applyCorsHeaders(res);
+    const pathname = pathnameOf(req);
+
+    if (req.method === "OPTIONS") {
+      res.statusCode = 200;
+      res.end();
+      return;
+    }
+
+    if (pathname === "/" && (req.method === "GET" || req.method === "HEAD")) {
+      sendJson(res, 200, {
+        ok: true,
+        module: options.name,
+        version: options.version,
+        status: options.handlers.rpc ? "ready" : "loading",
+        endpoints: {
+          health: "/health",
+          docs: apiPrefix,
+          rpc: rpcPrefix,
+        },
+      });
+      return;
+    }
+
+    if (pathname === "/health" && (req.method === "GET" || req.method === "HEAD")) {
+      sendText(res, 200, "OK");
+      return;
+    }
+
+    if (pathname.startsWith(`${rpcPrefix}/`)) {
+      if (!options.handlers.rpc) {
+        sendJson(res, 503, { error: "Plugin still loading..." });
+        return;
+      }
+      handleOrpc(
+        req,
+        res,
+        options.handlers.rpc,
+        rpcPrefix,
+        "RPC",
+        resolveEffectContext(),
+        resolvedPort,
+      ).catch(() => {});
+      return;
+    }
+
+    if (pathname === apiPrefix || pathname.startsWith(`${apiPrefix}/`)) {
+      if (!options.handlers.api) {
+        sendJson(res, 503, { error: "Plugin still loading..." });
+        return;
+      }
+      handleOrpc(
+        req,
+        res,
+        options.handlers.api,
+        apiPrefix,
+        "OpenAPI",
+        resolveEffectContext(),
+        resolvedPort,
+      ).catch(() => {});
+      return;
+    }
+
+    if (staticHandler) {
+      staticHandler(req, res, () => {
+        sendText(res, 404, "Not Found");
+      });
+      return;
+    }
+
+    sendText(res, 404, "Not Found");
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, () => resolve());
+  });
+
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    throw new Error("Failed to resolve host port");
+  }
+  resolvedPort = address.port;
+
+  return {
+    port: resolvedPort,
+    close: async () => {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}

package/src/dev/serve.ts

@@ -10,6 +10,7 @@ import { getPluginInfo, loadDevConfig } from "../build/rspack/utils";
 import { ensureGeneratedUiRsbuildConfig, pluginLayoutKey } from "../build/ui/generated-config";
 import { PLUGIN_ERROR_STATUS_MAP } from "../errors";
 import { loadRemoteWithRetry } from "../remote-entry";
+import { startDirectModuleHost } from "./host";
 import { killChildEscalating, watchParentDeath } from "./watch-kill";
 
 const corsHeaders = {
@@ -81,12 +82,6 @@ const loadPluginWithRetry = (
     }),
   );
 
-const sendJson = (res: http.ServerResponse, status: number, body: unknown) => {
-  res.statusCode = status;
-  res.setHeader("content-type", "application/json; charset=utf-8");
-  res.end(JSON.stringify(body));
-};
-
 const sendText = (res: http.ServerResponse, status: number, text: string) => {
   res.statusCode = status;
   res.setHeader("content-type", "text/plain; charset=utf-8");
@@ -125,7 +120,6 @@ export async function startPluginDevServer(
   const compositionKey = pluginLayoutKey(cwd) ?? pluginId;
   const port = options.port ?? (Number(process.env.PORT) || devConfig?.port || 3999);
   const rpcPrefix = normalizePrefix(devConfig?.prefix);
-  const rpcBase = `/api/rpc${rpcPrefix}`;
 
   const distDir = path.join(cwd, "dist");
   const serveStatic = sirv(distDir, { dev: true });
@@ -208,134 +202,19 @@ export async function startPluginDevServer(
   const handlers: { rpc: any; api: any } = { rpc: null, api: null };
   const effectContextHolder: { context: unknown } = { context: null };
   let runtime: { shutdown: () => Promise<void> } | null = null;
-
-  const pathnameOf = (req: http.IncomingMessage): string =>
-    ((req.url ?? "/").split("?")[0] ?? "/").replace(/\/+$/, "") || "/";
-
-  const buildDevContext = (_req: http.IncomingMessage, webRequest: Request) => {
-    const rawClone =
-      webRequest.method === "GET" || webRequest.method === "HEAD" ? null : webRequest.clone();
-    let cachedRawBody: string | null = null;
-    return {
-      reqHeaders: webRequest.headers,
-      "effect/context": effectContextHolder.context,
-      getRawBody: async (): Promise<string> => {
-        if (cachedRawBody !== null) return cachedRawBody;
-        if (!rawClone) {
-          cachedRawBody = "";
-          return cachedRawBody;
-        }
-        cachedRawBody = await rawClone.text();
-        return cachedRawBody;
-      },
-    };
-  };
-
-  const toWebRequest = (req: http.IncomingMessage): Request => {
-    const url = `http://localhost:${port}${req.url}`;
-    return new Request(url, {
-      method: req.method,
-      headers: req.headers,
-      body: req.method !== "GET" && req.method !== "HEAD" ? req : undefined,
-      duplex: req.method !== "GET" && req.method !== "HEAD" ? "half" : undefined,
-    } as RequestInit);
-  };
-
-  const handleOrpc = async (
-    req: http.IncomingMessage,
-    res: http.ServerResponse,
-    handler: any,
-    prefix: string,
-    errorLabel: string,
-  ) => {
-    try {
-      const webRequest = toWebRequest(req);
-      const result = await handler.handle(webRequest, {
-        prefix,
-        context: buildDevContext(req, webRequest),
-      });
-
-      if (result.response) {
-        res.statusCode = result.response.status;
-        result.response.headers.forEach((value: string, key: string) => {
-          res.setHeader(key, value);
-        });
-        const text = await result.response.text();
-        if (!res.getHeader("content-length")) {
-          res.setHeader("content-length", Buffer.byteLength(text).toString());
-        }
-        res.end(text);
-      } else {
-        sendText(res, 404, "Not Found");
-      }
-    } catch (error) {
-      console.error(`${errorLabel} error:`, error);
-      sendJson(res, 500, { error: (error as Error).message });
-    }
-  };
-
-  const server = http.createServer((req, res) => {
-    applyCorsHeaders(res);
-    const pathname = pathnameOf(req);
-
-    if (req.method === "OPTIONS") {
-      res.statusCode = 200;
-      res.end();
-      return;
-    }
-
-    if (pathname === "/" && (req.method === "GET" || req.method === "HEAD")) {
-      sendJson(res, 200, {
-        ok: true,
-        plugin: pluginInfo.normalizedName,
-        version: pluginInfo.version,
-        status: handlers.rpc ? "ready" : "loading",
-        endpoints: {
-          health: "/",
-          docs: "/api",
-          rpc: rpcBase,
-        },
-      });
-      return;
-    }
-
-    if (pathname === "/health" && (req.method === "GET" || req.method === "HEAD")) {
-      sendText(res, 200, "OK");
-      return;
-    }
-
-    if (pathname.startsWith(`${rpcBase}/`)) {
-      if (!handlers.rpc) {
-        sendJson(res, 503, { error: "Plugin still loading..." });
-        return;
-      }
-      handleOrpc(req, res, handlers.rpc, rpcBase, "RPC").catch(() => {});
-      return;
-    }
-
-    if (pathname === "/api" || pathname.startsWith("/api/")) {
-      if (!handlers.api) {
-        sendJson(res, 503, { error: "Plugin still loading..." });
-        return;
-      }
-      handleOrpc(req, res, handlers.api, "/api", "OpenAPI").catch(() => {});
-      return;
-    }
-
-    serveStatic(req, res, () => {
-      sendText(res, 404, "Not Found");
-    });
-  });
-
-  await new Promise<void>((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(port, () => resolve());
+  const host = await startDirectModuleHost({
+    name: pluginInfo.normalizedName,
+    version: pluginInfo.version,
+    handlers,
+    effectContext: () => effectContextHolder.context,
+    port,
+    staticHandler: serveStatic,
   });
 
-  console.log(`🚀 ${pluginInfo.name} dev server listening on port ${port}`);
-  console.log(`├─ 📡 RPC:    http://localhost:${port}/api/rpc${rpcPrefix}`);
-  console.log(`├─ 📖 Docs:   http://localhost:${port}/api`);
-  console.log(`└─ 💚 Health: http://localhost:${port}/`);
+  console.log(`🚀 ${pluginInfo.name} dev server listening on port ${host.port}`);
+  console.log(`├─ 📡 RPC:    http://localhost:${host.port}/api/rpc${rpcPrefix}`);
+  console.log(`├─ 📖 Docs:   http://localhost:${host.port}/api`);
+  console.log(`└─ 💚 Health: http://localhost:${host.port}/`);
 
   const load = async () => {
     try {
@@ -360,7 +239,7 @@ export async function startPluginDevServer(
 
       const registry: Record<string, { remote: string }> = {
         [pluginId]: {
-          remote: `http://localhost:${port}/${DEV_ENTRY_FILENAME}`,
+          remote: `http://localhost:${host.port}/${DEV_ENTRY_FILENAME}`,
         },
         ...siblings,
       };
@@ -440,8 +319,8 @@ export async function startPluginDevServer(
     if (uiStaticServer) {
       await new Promise<void>((resolve) => uiStaticServer.close(() => resolve()));
     }
+    await host.close();
     if (runtime) await runtime.shutdown().catch(() => {});
-    await new Promise<void>((resolve) => server.close(() => resolve()));
   };
 
   process.once("SIGINT", async () => {

package/src/errors.ts

@@ -125,9 +125,10 @@ export const PLUGIN_ERROR_STATUS_MAP: Record<string, number> = {
   CONNECTION_ERROR: 502,
 } as const;
 
-export type { PluginLoadFailureInfo } from "./runtime/errors";
+export type { PluginLoadFailureInfo, PluginWarningInfo } from "./runtime/errors";
 export {
   classifyPluginFailure,
+  defaultMissingSecretWarnings,
   extractFromFiberFailure,
   formatORPCError,
   ModuleFederationError,

package/src/index.ts

@@ -1,5 +1,6 @@
 import "@orpc/openapi/extensions/route";
 
+export * from "./client";
 export * from "./effect-helpers";
 export * from "./errors";
 export * from "./plugin";
@@ -13,10 +14,16 @@ export type {
   EveryPlugin,
   InitializedPlugin,
   LoadedPlugin,
+  ModuleClientEntry,
+  ModuleEndpoint,
+  ModuleSurface,
+  ModuleTransport,
+  PluginClientEntry,
   PluginClientType,
   PluginConfigInput,
   PluginContext,
   PluginContract,
+  PluginEndpoint,
   PluginInstance,
   PluginMetadata,
   PluginRegistry,
@@ -24,6 +31,8 @@ export type {
   PluginRuntimeConfig,
   PluginSecrets,
   PluginServicesEntry,
+  PluginSurface,
+  PluginTransport,
   PluginVariables,
   RegisteredPlugins,
   SecretsConfig,

package/src/plugin.ts

@@ -5,6 +5,7 @@ import type { ContractedRouter, Implementer } from "@orpc/server";
 import { implement } from "@orpc/server";
 import type { Scope } from "effect";
 import { Context, Effect, Layer } from "effect";
+import type { PluginWarningInfo } from "./runtime/errors";
 import { type PluginRuntimeError, toPluginRuntimeError } from "./runtime/errors";
 
 type ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;
@@ -19,11 +20,20 @@ export type PluginConfigFor<
   context: TRequestContext;
 };
 
-type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+export type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
   variables: InferSchemaOutput<V>;
   secrets: InferSchemaOutput<S>;
 };
 
+/**
+ * A plugin's own config-derived warnings, evaluated once with the validated
+ * config after initialization. Declaring `warnings` opts the plugin out of
+ * the loader's default missing-secret warning — these messages replace it.
+ */
+export type PluginWarningsFn<V extends AnySchema, S extends AnySchema> = (
+  config: PluginInitializeInput<V, S>,
+) => PluginWarningInfo[] | string[];
+
 export class PluginIdTag extends Context.Service<PluginIdTag, string>()("PluginId") {}
 
 /**
@@ -50,6 +60,13 @@ type PluginDefinition<
    * module statically.
    */
   servicesTag?: Context.Key<any, any>;
+  /**
+   * Optional warnings function evaluated once with the validated config after
+   * initialization. Returns structured non-fatal warnings (e.g. an optional
+   * secret was not set, so the feature depending on it is disabled).
+   * Declaring it opts out of the loader's default missing-secret warning.
+   */
+  warnings?: PluginWarningsFn<V, S>;
   /**
    * Initialize the plugin by returning an Effect `Layer`.
    *
@@ -107,6 +124,7 @@ export interface Plugin<
   readonly contract: TContract;
   readonly configSchema: PluginConfigFor<TVariables, TSecrets, TRequestContext>;
   readonly servicesTag?: Context.Key<any, any>;
+  readonly warnings?: PluginWarningsFn<TVariables, TSecrets>;
 
   initialize(
     config: PluginInitializeInput<TVariables, TSecrets>,
@@ -156,6 +174,7 @@ export const createPlugin: CreatePluginFn = function createPlugin<
     readonly contract = config.contract;
     readonly configSchema = configSchema;
     readonly servicesTag = config.servicesTag;
+    readonly warnings = config.warnings;
 
     initialize(
       pluginConfig: PluginInitializeInput<V, S>,

package/src/runtime/errors.ts

@@ -282,6 +282,50 @@ export interface PluginLoadFailureInfo {
   dbUrlMasked?: string;
 }
 
+/**
+ * Structured, serializable warning surfaced alongside plugin failures in
+ * health endpoints and dashboards. Warnings are non-fatal: the plugin loaded
+ * and initialized successfully, but runs with reduced functionality (e.g. an
+ * optional secret was not set, so the feature depending on it is disabled).
+ */
+export interface PluginWarningInfo {
+  /** loader-side key (host entry key, dev plugin id) */
+  pluginKey: string;
+  message: string;
+  hint?: string;
+}
+
+/**
+ * The loader's default warning policy for declared-but-unset secrets: a
+ * successfully initialized plugin whose declared secret names resolved to
+ * nothing (missing or empty in the environment) gets one consolidated
+ * warning. `*_DATABASE_URL` keys are excluded — they have the shared-API-DB
+ * fallback, and a genuinely-missing DB URL fails initialization (a `failure`,
+ * not a warning). A plugin that declares its own `warnings` function opts out
+ * of this default.
+ */
+export const defaultMissingSecretWarnings = (
+  pluginKey: string,
+  declaredKeys: readonly string[],
+  resolvedKeys: readonly string[],
+): PluginWarningInfo[] => {
+  const resolved = new Set(resolvedKeys);
+  const missing = declaredKeys.filter(
+    (key) => !resolved.has(key) && !key.endsWith("_DATABASE_URL"),
+  );
+  if (missing.length === 0) return [];
+  return [
+    {
+      pluginKey,
+      message:
+        missing.length === 1
+          ? `Declared secret ${missing[0]} is not set — features depending on it are disabled`
+          : `${missing.length} declared secrets are not set: ${missing.join(", ")} — features depending on them are disabled`,
+      hint: "Set the secret(s) in your environment (.env in development); see the plugin's config schema for what each enables",
+    },
+  ];
+};
+
 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([

package/src/runtime/services/module-federation.service.ts

@@ -111,13 +111,10 @@ const resolveRemoteSelfName = (pluginId: string, url: string) =>
     const memo = remoteSelfNames.get(memoKey);
     if (memo) return memo;
 
-    let selfName: string | null = null;
-    try {
-      const manifest = yield* Effect.promise(() => fetchRemoteIdentityManifest(url));
-      selfName = manifest?.metaData?.name?.trim() || null;
-    } catch {
-      selfName = null;
-    }
+    const manifest = yield* Effect.tryPromise(() => fetchRemoteIdentityManifest(url)).pipe(
+      Effect.orElseSucceed(() => null),
+    );
+    const selfName = manifest?.metaData?.name?.trim() || null;
 
     const resolved = selfName ?? getNormalizedRemoteName(pluginId);
     remoteSelfNames.set(memoKey, resolved);

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

@@ -11,11 +11,39 @@ 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";
 
+/**
+ * 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",
 ) {}
@@ -313,6 +341,10 @@ export const PluginLoaderServiceDefault = Layer.effect(
             config: { variables: _variables, secrets: hydratedConfig.secrets },
             effectContext,
             scope,
+            warnings: collectPluginWarnings(plugin, {
+              variables: _variables,
+              secrets: hydratedConfig.secrets,
+            }),
           } satisfies InitializedPlugin<T>;
         }),
     };

package/src/runtime/services/shared-identity.ts

@@ -19,7 +19,7 @@ function manifestUrl(remoteUrl: string): string {
 
 function normalizeBaseUrl(remoteUrl: string): string {
   const withoutHash = remoteUrl.split("#")[0] ?? remoteUrl;
-  return withoutHash.replace(/\/(mf-manifest\.json|remoteEntry\.js)$/i, "");
+  return withoutHash.replace(/\/(mf-manifest\.json|remoteEntry(?:\.[^/]+)?\.js)$/i, "");
 }
 
 export function compareSharedIdentity(