every-plugin 3.0.0-rc.3 → 3.0.0-rc.5

package/src/client.ts

@@ -0,0 +1,111 @@
+import { createORPCClient, onError } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import type { ContractRouterClient, RouterContract } from "@orpc/contract";
+
+export type RpcConnectionErrorCopy = () => { title: string; description: string };
+
+export interface RpcClientConfig {
+  hostUrl: string;
+  path: `/${string}`;
+  connectionError?: RpcConnectionErrorCopy;
+}
+
+const RATE_LIMIT_MAX_RETRIES = 3;
+const RATE_LIMIT_RETRY_CAP_MS = 2_000;
+const browserClients = new Map<string, unknown>();
+type FetchInput = Parameters<typeof fetch>[0];
+
+async function fetchWithRateLimitRetry(
+  fetchUrl: FetchInput,
+  options?: RequestInit,
+): Promise<Response> {
+  let response = await fetch(fetchUrl, options);
+  for (let attempt = 1; attempt <= RATE_LIMIT_MAX_RETRIES && response.status === 429; attempt++) {
+    const retryAfterSeconds = Number(response.headers.get("retry-after"));
+    const delay =
+      Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+        ? Math.min(retryAfterSeconds * 1000, RATE_LIMIT_RETRY_CAP_MS)
+        : 100 * attempt;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    response = await fetch(fetchUrl, options);
+  }
+
+  return response;
+}
+
+function createRpcLink(config: RpcClientConfig, headers?: Headers) {
+  return new RPCLink({
+    origin: config.hostUrl,
+    url: config.path,
+    interceptors: [
+      onError((error: unknown) => {
+        const browserWindow = (globalThis as { window?: unknown }).window;
+        if (typeof browserWindow === "undefined") {
+          return;
+        }
+
+        if (error && typeof error === "object" && "message" in error) {
+          const message = String(error.message).toLowerCase();
+          if (
+            message.includes("fetch") ||
+            message.includes("network") ||
+            message.includes("failed to fetch")
+          ) {
+            void import("sonner")
+              .then(({ toast }) => {
+                const message = config.connectionError?.() ?? {
+                  title: "Unable to connect to API",
+                  description: "The API is currently unavailable. Please try again later.",
+                };
+                toast.error(message.title, {
+                  id: "api-connection-error",
+                  description: message.description,
+                });
+              })
+              .catch(() => {});
+          }
+        }
+      }),
+    ],
+    fetch(fetchUrl: FetchInput, options?: RequestInit) {
+      return fetchWithRateLimitRetry(fetchUrl, {
+        ...options,
+        credentials: "include",
+        headers: headers
+          ? { ...Object.fromEntries(headers), ...(options?.headers as Record<string, string>) }
+          : options?.headers,
+      });
+    },
+  });
+}
+
+function buildRpcClient<T extends RouterContract>(
+  config: RpcClientConfig,
+  headers?: Headers,
+): ContractRouterClient<T> {
+  if (!config.hostUrl) {
+    throw new Error("Missing runtime host URL");
+  }
+
+  return createORPCClient(createRpcLink(config, headers)) as ContractRouterClient<T>;
+}
+
+export function createRpcClient<T extends RouterContract = RouterContract>(
+  config: RpcClientConfig,
+  headers?: Headers,
+): ContractRouterClient<T> {
+  const browserWindow = (globalThis as { window?: unknown }).window;
+  if (typeof browserWindow !== "undefined" && !headers) {
+    const key = `${config.hostUrl}${config.path}`;
+    const memoized = browserClients.get(key);
+    if (memoized) {
+      return memoized as ContractRouterClient<T>;
+    }
+
+    const client = buildRpcClient<T>(config, headers);
+    browserClients.set(key, client);
+    return client;
+  }
+
+  return buildRpcClient<T>(config, headers);
+}

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

@@ -7,9 +7,14 @@ import sirv from "sirv";
 import { DEV_ENTRY_FILENAME } from "../build/artifact-names";
 import { ensureGeneratedRspackConfig } from "../build/rspack/generated-config";
 import { getPluginInfo, loadDevConfig } from "../build/rspack/utils";
-import { ensureGeneratedUiRsbuildConfig, pluginLayoutKey } from "../build/ui/generated-config";
+import {
+  ensureGeneratedUiRsbuildConfig,
+  pluginLayoutKey,
+  uiDistDirFor,
+} 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 +86,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 +124,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 });
@@ -174,11 +172,10 @@ export async function startPluginDevServer(
     // Folder-form ui: one-shot build, then serve the ui source root's dist
     // (the factory's absolute distPath target) statically on the ui port.
     await runOnce("rsbuild", ["build", "--config", uiConfig]);
-    const uiDistDir =
-      path.basename(cwd) === "ui" ? path.join(cwd, "dist") : path.join(cwd, "ui", "dist");
+    const uiDistDir = uiDistDirFor(cwd);
     if (!fs.existsSync(path.join(uiDistDir, DEV_ENTRY_FILENAME))) {
-      console.error(
-        `❌ UI dist is missing at ${uiDistDir} — the ui static server would serve 404s for every asset (build output layout mismatch?)`,
+      throw new Error(
+        `❌ UI dist is missing at ${uiDistDir} after the rsbuild one-shot — build output layout mismatch?`,
       );
     }
     const serveUiStatic = sirv(uiDistDir, { dev: true });
@@ -208,134 +205,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 +242,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 +322,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/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/remote-entry.ts

@@ -23,8 +23,7 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 const RETRY_BASE_DELAY_MS = 500;
 const RETRY_MAX_DELAY_MS = 5_000;
 
-export const sleep = (ms: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(resolve, ms));
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
 
 /**
  * Deletes the failed remote's keys from the process-global entry-load cache.

package/src/types.ts

@@ -24,6 +24,24 @@ import type { PluginWarningInfo } from "./runtime/errors";
 // biome-ignore lint/suspicious/noEmptyInterface: required for module augmentation pattern
 export interface RegisteredPlugins {}
 
+export type ModuleTransport = "inproc" | "rpc" | "mf";
+
+export type ModuleSurface = "api" | "ui" | "jobs";
+
+export interface ModuleEndpoint {
+  readonly transport: ModuleTransport;
+  readonly surface?: ModuleSurface;
+  readonly url: string;
+  readonly path?: `/${string}`;
+  readonly manifest?: string;
+}
+
+export type PluginTransport = ModuleTransport;
+
+export type PluginSurface = ModuleSurface;
+
+export type PluginEndpoint = ModuleEndpoint;
+
 /**
  * Base type for any plugin instance.
  */
@@ -46,8 +64,14 @@ export type AnyPluginConstructor = {
  * Registry entry that supports both direct module imports and remote URLs
  */
 export type PluginRegistryEntry =
-  | { module: AnyPluginConstructor; remote?: string; version?: string; description?: string }
-  | { remote: string; version?: string; description?: string };
+  | {
+      module: AnyPluginConstructor;
+      remote?: string;
+      endpoint?: PluginEndpoint;
+      version?: string;
+      description?: string;
+    }
+  | { remote: string; endpoint?: PluginEndpoint; version?: string; description?: string };
 
 /**
  * Extract plugin constructor type from registry entry
@@ -116,8 +140,18 @@ export type PluginClientType<T> = RouterClient<PluginRouterType<T>>;
 export type PluginServicesEntry<T = any> = {
   client: (context?: PluginContextInput<T>) => PluginClientType<T>;
   router: PluginRouterType<T>;
+  endpoint?: PluginEndpoint;
 };
 
+export type ModuleClientEntry<C extends AnyContractRouter = AnyContractRouter> = {
+  client: (context?: Record<string, unknown>) => RouterClient<ContractedRouter<C, any>>;
+  router?: ContractedRouter<C, any>;
+  endpoint?: PluginEndpoint;
+};
+
+export type PluginClientEntry<C extends AnyContractRouter = AnyContractRouter> =
+  ModuleClientEntry<C>;
+
 /**
  * Extract plugin type from registered plugins by key
  * @param K - The plugin key