every-plugin 2.10.1 → 3.0.0-rc.10

package/src/plugin.ts

@@ -1,9 +1,12 @@
 import type { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
-import { ORPCError } from "@orpc/contract";
-import type { Implementer, Router } from "@orpc/server";
-import { implement, onError } from "@orpc/server";
-import { Context, Effect, type Context as EffectContext, type Layer, type Scope } from "effect";
-import { extractFromFiberFailure, formatORPCError } from "./runtime/errors";
+import type { WithEffectContext } from "@orpc/experimental-effect";
+import "@orpc/experimental-effect/extensions/effect";
+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>;
 
@@ -17,28 +20,39 @@ export type PluginConfigFor<
   context: TRequestContext;
 };
 
-type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+export type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+  /**
+   * The framework-assigned plugin id — the same key the host uses for secret
+   * injection and per-plugin database namespacing. Arrives as a value so
+   * plugin code never needs the ambient `PluginIdTag`.
+   */
+  pluginId: string;
   variables: InferSchemaOutput<V>;
   secrets: InferSchemaOutput<S>;
 };
 
 /**
- * Tools provided to plugin initialize/services for building long-lived scoped resources.
+ * 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.
  */
-type ServiceOf<T> = T extends EffectContext.Tag<any, infer S> ? S : never;
+export type PluginWarningsFn<V extends AnySchema, S extends AnySchema> = (
+  config: PluginInitializeInput<V, S>,
+) => PluginWarningInfo[] | string[];
 
-export type PluginServicesTools = {
-  buildService: <T>(tag: T, layer: Layer.Layer<any, any, any>) => Effect.Effect<ServiceOf<T>>;
-};
+export class PluginIdTag extends Context.Service<PluginIdTag, string>()("PluginId") {}
 
-export class PluginIdTag extends Context.Tag("PluginId")<PluginIdTag, string>() {}
+/**
+ * The `initialize` effect's environment: the plugin lifecycle scope plus the
+ * framework-assigned plugin id.
+ */
+export type PluginEnv = Scope.Scope | PluginIdTag;
 
 type PluginDefinition<
   V extends AnySchema,
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Record<string, any>,
   P extends Record<string, unknown>,
 > = {
   variables: V;
@@ -46,20 +60,42 @@ type PluginDefinition<
   contract: TContract;
   context?: TRequestContext;
   /**
-   * Initialize the plugin and build dependencies.
-   * A third argument `tools` is provided for building long-lived scoped resources
-   * (e.g. database pools) via `tools.buildService(tag, layer)`.
+   * Optional tag under which `initialize` exposes the plugin's services.
+   * The host uses it to read services (e.g. the auth plugin's Better Auth
+   * handler) from the built Effect context without importing the plugin
+   * 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`.
+   *
+   * The runtime builds the Layer against the plugin's lifecycle scope —
+   * scoped resources (db pools, repositories, caches, publishers) release
+   * when the plugin shuts down. Services are provided to `.effect()`
+   * handlers via the oRPC context (`yield* Tag`).
    */
   initialize?: (
     config: PluginInitializeInput<V, S>,
     plugins: P,
-    tools: PluginServicesTools,
-  ) => Effect.Effect<TDeps, Error, Scope.Scope>;
+  ) => Effect.Effect<Layer.Layer<any, Error, PluginEnv>, Error, PluginEnv>;
+  /**
+   * Creates the strongly-typed oRPC router for this plugin.
+   * Services come from the Effect context — access them with
+   * `yield* Tag` in `.effect()` handlers, or
+   * `Context.get(context["effect/context"], Tag)` in plain handlers.
+   * Sibling plugin entries in `plugins` carry `{ client, router }`.
+   */
   createRouter: (
-    deps: TDeps,
-    builder: Implementer<TContract, ContextOutput<TRequestContext>, ContextOutput<TRequestContext>>,
-  ) => Router<TContract, any>;
-  shutdown?: (deps: TDeps) => Effect.Effect<void, Error, never>;
+    builder: Implementer<TContract, ContextOutput<TRequestContext> & WithEffectContext<any>>,
+    plugins: P,
+  ) => ContractedRouter<TContract, any>;
 };
 
 /**
@@ -70,14 +106,14 @@ export interface LoadedPluginWithBinding<
   TVariables extends AnySchema,
   TSecrets extends AnySchema,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
 > {
-  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext, TDeps>;
+  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext>;
   binding: {
     contract: TContract;
     variables: TVariables;
     secrets: TSecrets;
     context: TRequestContext;
+    servicesTag?: Context.Key<any, any>;
   };
 }
 
@@ -89,27 +125,26 @@ export interface Plugin<
   TVariables extends AnySchema,
   TSecrets extends AnySchema,
   TRequestContext extends AnySchema | undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
 > {
   readonly id: string;
   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>,
     plugins: Record<string, unknown>,
-    tools: PluginServicesTools,
-  ): Effect.Effect<TDeps, unknown, Scope.Scope>;
-
-  shutdown(): Effect.Effect<void, never>;
+  ): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv>;
 
   /**
    * Creates the strongly-typed oRPC router for this plugin.
    * The router's procedure types are inferred directly from the contract.
-   * @param deps The initialized plugin dependencies
+   * @param plugins Sibling plugin entries (`{ client, router }`) for
+   * cross-plugin composition
    * @returns A router with procedures matching the plugin's contract
    */
-  createRouter(deps: TDeps): Router<TContract, any>;
+  createRouter(plugins: Record<string, unknown>): ContractedRouter<TContract, any>;
 }
 
 export interface CreatePluginFn {
@@ -118,11 +153,10 @@ export interface CreatePluginFn {
     S extends AnySchema,
     TContract extends AnyContractRouter,
     TRequestContext extends AnySchema | undefined = undefined,
-    TDeps extends Record<string, any> = Record<never, never>,
     P extends Record<string, unknown> = Record<string, never>,
   >(
-    config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
-  ): LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+    config: PluginDefinition<V, S, TContract, TRequestContext, P>,
+  ): LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
 
   withPlugins: <P extends Record<string, unknown>>() => CreatePluginWithPlugins<P>;
 }
@@ -132,84 +166,54 @@ export const createPlugin: CreatePluginFn = function createPlugin<
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined = undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
   P extends Record<string, unknown> = Record<string, never>,
->(config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>) {
+>(config: PluginDefinition<V, S, TContract, TRequestContext, P>) {
   const configSchema: PluginConfigFor<V, S, TRequestContext> = {
     variables: config.variables,
     secrets: config.secrets,
     context: config.context as TRequestContext,
   };
 
-  class CreatedPlugin implements Plugin<TContract, V, S, TRequestContext, TDeps> {
+  class CreatedPlugin implements Plugin<TContract, V, S, TRequestContext> {
     /** set during instantiation - registry key */
     id!: string;
     readonly contract = config.contract;
     readonly configSchema = configSchema;
-
-    private _deps: TDeps | null = null;
+    readonly servicesTag = config.servicesTag;
+    readonly warnings = config.warnings;
 
     initialize(
       pluginConfig: PluginInitializeInput<V, S>,
       plugins: Record<string, unknown> = {},
-      tools: PluginServicesTools,
-    ): Effect.Effect<TDeps, unknown, Scope.Scope> {
-      const init = config.initialize ?? (() => Effect.succeed({} as TDeps));
-
-      return init(pluginConfig, plugins as P, tools).pipe(
-        Effect.tap((deps) =>
-          Effect.sync(() => {
-            this._deps = deps;
-          }),
+    ): Effect.Effect<Layer.Layer<any, Error, PluginEnv>, PluginRuntimeError, PluginEnv> {
+      const init = config.initialize;
+      if (!init) {
+        return Effect.succeed(Layer.empty as unknown as Layer.Layer<any, Error, PluginEnv>);
+      }
+
+      return init(pluginConfig, plugins as P).pipe(
+        Effect.mapError((error) =>
+          toPluginRuntimeError(error, this.id, undefined, "initialize-plugin"),
         ),
-        Effect.map(() => this._deps as TDeps),
-        Effect.mapError((error) => error as unknown),
       );
     }
 
-    shutdown(): Effect.Effect<void, never> {
-      const self = this;
-      return Effect.gen(function* () {
-        if (config.shutdown && self._deps) {
-          yield* config
-            .shutdown(self._deps)
-            .pipe(
-              Effect.catchAll((error) =>
-                Effect.logWarning(`Plugin shutdown hook failed for ${self.id}`, error),
-              ),
-            );
-        }
-        self._deps = null;
-      });
-    }
-
-    createRouter(deps: TDeps): Router<TContract, any> {
-      const base = implement(config.contract).$context<ContextOutput<TRequestContext>>();
-      const errorMiddleware = onError((error: unknown) => {
-        const unwrapped = extractFromFiberFailure(error);
-
-        if (unwrapped !== error && unwrapped instanceof ORPCError) {
-          throw unwrapped;
-        }
-
-        const formatted = formatORPCError(error);
-        if (formatted) console.error(formatted);
-        throw error;
-      }) as any;
-
-      const builder = (base as any).use(errorMiddleware);
-      const router = config.createRouter(deps, builder as any);
-      return router as Router<TContract, any>;
+    createRouter(plugins: Record<string, unknown>): ContractedRouter<TContract, any> {
+      const builder = implement(config.contract).$context<
+        ContextOutput<TRequestContext> & WithEffectContext<any>
+      >();
+      return config.createRouter(builder as any, plugins as P) as ContractedRouter<TContract, any>;
     }
   }
 
   const PluginConstructor = CreatedPlugin as unknown as {
-    new (): Plugin<TContract, V, S, TRequestContext, TDeps>;
+    new (): Plugin<TContract, V, S, TRequestContext>;
     binding: {
       contract: TContract;
       variables: V;
       secrets: S;
       context: TRequestContext;
+      servicesTag?: Context.Key<any, any>;
     };
   };
 
@@ -218,9 +222,10 @@ export const createPlugin: CreatePluginFn = function createPlugin<
     variables: config.variables,
     secrets: config.secrets,
     context: config.context as TRequestContext,
+    servicesTag: config.servicesTag,
   };
 
-  return PluginConstructor as LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+  return PluginConstructor as LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
 };
 
 export type CreatePluginWithPlugins<P extends Record<string, unknown>> = <
@@ -228,10 +233,9 @@ export type CreatePluginWithPlugins<P extends Record<string, unknown>> = <
   S extends AnySchema,
   TContract extends AnyContractRouter,
   TRequestContext extends AnySchema | undefined = undefined,
-  TDeps extends Record<string, any> = Record<never, never>,
 >(
-  config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
-) => LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+  config: PluginDefinition<V, S, TContract, TRequestContext, P>,
+) => LoadedPluginWithBinding<TContract, V, S, TRequestContext>;
 
 export function withPlugins<P extends Record<string, unknown>>(): CreatePluginWithPlugins<P> {
   return <
@@ -239,10 +243,9 @@ export function withPlugins<P extends Record<string, unknown>>(): CreatePluginWi
     S extends AnySchema,
     TContract extends AnyContractRouter,
     TRequestContext extends AnySchema | undefined = undefined,
-    TDeps extends Record<string, any> = Record<never, never>,
   >(
-    config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
-  ) => createPlugin<V, S, TContract, TRequestContext, TDeps, P>(config as any);
+    config: PluginDefinition<V, S, TContract, TRequestContext, P>,
+  ) => createPlugin<V, S, TContract, TRequestContext, P>(config as any);
 }
 
 createPlugin.withPlugins = withPlugins;

package/src/remote-entry.ts

@@ -0,0 +1,170 @@
+/**
+ * Remote-entry loading resilience — the ONE contract every MF consumer in
+ * the dev stack shares (plugin dev serves, the host's plugin loader).
+ *
+ * Two failure classes it exists for:
+ * 1. Cold compile: remoteEntry.js 404s until the remote's first build —
+ *    the 404 body gets eval'd as JS ("Unexpected identifier 'Found'").
+ * 2. Watch-rebuild poisoning: a failed entry load is memoized forever in
+ *    `globalThis.__GLOBAL_LOADING_REMOTE_ENTRY__` (runtime-core never evicts
+ *    rejections), so retries without a purge await the same failure.
+ */
+import { Duration, Effect, Schedule } from "effect";
+import type { PluginRuntimeError } from "./runtime/errors";
+import {
+  classifyPluginFailure,
+  deepestErrorStack,
+  type PluginFailureClassification,
+  toPluginRuntimeError,
+} from "./runtime/errors";
+
+const POLL_INTERVAL_MS = 300;
+const DEFAULT_TIMEOUT_MS = 120_000;
+const RETRY_BASE_DELAY_MS = 500;
+const RETRY_MAX_DELAY_MS = 5_000;
+
+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.
+ * Deleting a RESOLVED entry would force a wasteful re-eval, so only call
+ * this from failure paths.
+ */
+export const purgeRemoteEntryCache = (remoteUrl: string): void => {
+  const globalLoading = (globalThis as Record<string, unknown>).__GLOBAL_LOADING_REMOTE_ENTRY__ as
+    | Record<string, unknown>
+    | undefined;
+  if (!globalLoading) return;
+  for (const key of Object.keys(globalLoading)) {
+    if (key.endsWith(`:${remoteUrl}`)) delete globalLoading[key];
+  }
+};
+
+export const isRemoteEntryBody = (body: string): boolean =>
+  !/not found|<(!doctype|html)/i.test(body.slice(0, 64));
+
+export const waitForRemoteEntryReady = async (
+  label: string,
+  url: string,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<void> => {
+  const deadline = Date.now() + timeoutMs;
+  let announced = false;
+  while (Date.now() < deadline) {
+    const res = await fetch(url).catch(() => null);
+    if (res?.ok && isRemoteEntryBody(await res.text().catch(() => ""))) return;
+    if (!announced) {
+      announced = true;
+      console.log(`⏳ waiting for ${label} to compile (remote entry not ready)…`);
+    }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  throw new Error(`${label} remote entry never became ready at ${url}`);
+};
+
+export interface PluginLoadAttemptInfo {
+  attempt: number;
+  classification: PluginFailureClassification;
+}
+
+export interface PluginLoadRetryOptions<T> {
+  /** short plugin key for log prefixes (host entry key or plugin id) */
+  label: string;
+  remoteUrl: string;
+  load: () => Promise<T>;
+  /** wall-clock budget for the retry loop */
+  timeoutMs?: number;
+  /**
+   * Budget for the readiness poll (cold-compile wait) — defaults to the
+   * retry budget, preserving the historical behavior. Pass `0` to skip the
+   * poll (useful when the caller stubs `load` and does not need network).
+   */
+  readinessTimeoutMs?: number;
+  /**
+   * Observes every failed attempt (including non-retryable ones that end the
+   * loop). Defaults to classification-deduped console.error under the
+   * `[Plugins]` prefix.
+   */
+  onAttempt?: ((error: unknown, info: PluginLoadAttemptInfo) => void) | undefined;
+}
+
+/**
+ * The one plugin-load retry policy: poll the remote entry until it is actually
+ * served, then load with capped exponential backoff — purging the poisoned
+ * global entry cache between attempts so each retry genuinely re-fetches.
+ *
+ * Recovery policy is `classifyPluginFailure().retryable`: transient network
+ * conditions retry until the wall-clock budget runs out; permanent failures
+ * (MF identity skew, schema validation, dead remotes, TLS verification) fail
+ * fast on the first attempt instead of burning the budget silently.
+ *
+ * Fails with the ORIGINAL error from `load` — the host builds
+ * `PluginBootstrapError.cause` from it and classification walks it.
+ */
+export const loadRemoteWithRetry = <T>(
+  options: PluginLoadRetryOptions<T>,
+): Effect.Effect<T, PluginRuntimeError> => {
+  const {
+    label,
+    remoteUrl,
+    load,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    readinessTimeoutMs,
+    onAttempt,
+  } = options;
+  const readinessTimeout = readinessTimeoutMs ?? timeoutMs;
+
+  const schedule = Schedule.exponential(Duration.millis(RETRY_BASE_DELAY_MS)).pipe(
+    Schedule.modifyDelay(({ output }) =>
+      Effect.succeed(
+        Duration.toMillis(output) > RETRY_MAX_DELAY_MS
+          ? Duration.millis(RETRY_MAX_DELAY_MS)
+          : output,
+      ),
+    ),
+    Schedule.upTo({ duration: Duration.millis(timeoutMs) }),
+  );
+
+  let attempt = 0;
+  let lastSignature: string | undefined;
+  const reportFailure = (error: unknown): void => {
+    attempt += 1;
+    purgeRemoteEntryCache(remoteUrl);
+    const classification = classifyPluginFailure(error);
+    if (onAttempt) {
+      onAttempt(error, { attempt, classification });
+      return;
+    }
+    const signature = `${classification.kind}::${classification.message}`;
+    if (signature === lastSignature) return;
+    lastSignature = signature;
+    // The message alone is rarely enough, and the wrapper's own stack points
+    // at the wrapping frames — log the DEEPEST cause's stack (the original
+    // throw site inside the evaluated remote entry).
+    const stack = deepestErrorStack(error);
+    console.error(
+      `[Plugins][${label}] ❌ ${classification.kind} failure (attempt ${attempt}): ${classification.message}` +
+        (classification.suggestion ? `\n[Plugins][${label}] → ${classification.suggestion}` : "") +
+        (stack ? `\n[Plugins][${label}] ${stack}` : ""),
+    );
+  };
+
+  const loadWithRetry = Effect.tryPromise({
+    try: load,
+    catch: (error) => toPluginRuntimeError(error, label, undefined, "remote-entry-load"),
+  }).pipe(
+    Effect.tapError((error) => Effect.sync(() => reportFailure(error))),
+    Effect.retry({ schedule, while: (error) => classifyPluginFailure(error).retryable }),
+  );
+
+  // readinessTimeoutMs: 0 skips the cold-compile poll (tests stub `load` and
+  // must not race a 1ms wall-clock window against the event loop).
+  if (readinessTimeout === 0) {
+    return loadWithRetry;
+  }
+
+  return Effect.tryPromise({
+    try: () => waitForRemoteEntryReady(label, remoteUrl, readinessTimeout),
+    catch: (error) => toPluginRuntimeError(error, label, undefined, "remote-entry-readiness"),
+  }).pipe(Effect.flatMap(() => loadWithRetry));
+};