every-plugin 0.8.9 → 2.2.2

package/src/errors.ts

@@ -0,0 +1,140 @@
+import { z } from "./zod";
+
+/**
+ * Error pattern constants for categorizing infrastructure errors
+ */
+export const ERROR_PATTERNS = {
+  CONNECTION_REFUSED: ["ECONNREFUSED"],
+  HOST_NOT_FOUND: ["ENOTFOUND", "EHOSTUNREACH"],
+  TIMEOUT: ["ETIMEDOUT", "ESOCKETTIMEDOUT", "timeout"],
+  CONNECTION_RESET: ["ECONNRESET", "EPIPE"],
+  PERMISSION: ["EACCES", "EPERM", "permission denied"],
+  AUTH: ["401", "unauthorized", "authentication failed"],
+  RATE_LIMITED: ["429", "too many requests", "rate limit"],
+  SERVICE_UNAVAILABLE: ["503", "service unavailable"],
+} as const;
+
+/**
+ * Common error schemas for plugin contracts.
+ * Import individually or use the grouped PluginErrors export.
+ *
+ * @example
+ * ```typescript
+ * import { NOT_FOUND, FORBIDDEN, UNAUTHORIZED } from "every-plugin/errors";
+ *
+ * export const contract = oc.router({
+ *   getData: oc.route(...)
+ *     .errors({ NOT_FOUND, FORBIDDEN, UNAUTHORIZED })
+ * });
+ * ```
+ */
+
+export const UNAUTHORIZED = {
+  status: 401,
+  data: z.object({
+    apiKeyProvided: z.boolean(),
+    provider: z.string().optional(),
+    authType: z.enum(["apiKey", "oauth", "token"]).optional(),
+  }),
+} as const;
+
+export const RATE_LIMITED = {
+  status: 429,
+  data: z.object({
+    retryAfter: z.number().int().min(1),
+    remainingRequests: z.number().int().min(0).optional(),
+    resetTime: z.string().datetime().optional(),
+    limitType: z.enum(["requests", "tokens", "bandwidth"]).optional(),
+  }),
+} as const;
+
+export const SERVICE_UNAVAILABLE = {
+  status: 503,
+  data: z.object({
+    retryAfter: z.number().int().optional(),
+    maintenanceWindow: z.boolean().default(false),
+    estimatedUptime: z.string().datetime().optional(),
+  }),
+} as const;
+
+export const BAD_REQUEST = {
+  status: 400,
+  data: z.object({
+    invalidFields: z.array(z.string()).optional(),
+    validationErrors: z
+      .array(
+        z.object({
+          field: z.string(),
+          message: z.string(),
+          code: z.string().optional(),
+        }),
+      )
+      .optional(),
+  }),
+} as const;
+
+export const NOT_FOUND = {
+  status: 404,
+  data: z.object({
+    resource: z.string().optional(),
+    resourceId: z.string().optional(),
+  }),
+} as const;
+
+export const FORBIDDEN = {
+  status: 403,
+  data: z.object({
+    requiredPermissions: z.array(z.string()).optional(),
+    action: z.string().optional(),
+  }),
+} as const;
+
+export const TIMEOUT = {
+  status: 504,
+  data: z.object({
+    timeoutMs: z.number().int().min(0).optional(),
+    operation: z.string().optional(),
+    retryable: z.boolean().default(true),
+  }),
+} as const;
+
+export const CONNECTION_ERROR = {
+  status: 502,
+  data: z.object({
+    errorCode: z.string().optional(),
+    host: z.string().optional(),
+    port: z.number().int().optional(),
+    suggestion: z.string().optional(),
+  }),
+} as const;
+
+/**
+ * Grouped export for all plugin errors.
+ * Use individual imports for cleaner code.
+ */
+export const PluginErrors = {
+  UNAUTHORIZED,
+  RATE_LIMITED,
+  SERVICE_UNAVAILABLE,
+  BAD_REQUEST,
+  NOT_FOUND,
+  FORBIDDEN,
+  TIMEOUT,
+  CONNECTION_ERROR,
+} as const;
+
+/**
+ * @deprecated Use individual imports or PluginErrors instead
+ */
+export const CommonPluginErrors = PluginErrors;
+
+export {
+  extractFromFiberFailure,
+  formatORPCError,
+  isRetryableORPCCode,
+  ModuleFederationError,
+  PluginRuntimeError,
+  toPluginRuntimeError,
+  ValidationError,
+  wrapORPCError,
+} from "./runtime/errors";

package/src/index.ts

@@ -0,0 +1,26 @@
+export * from "./errors";
+export * from "./plugin";
+export * from "./runtime";
+
+// Re-export the normalize helper for build configs
+export { getNormalizedRemoteName } from "./runtime/services/normalize";
+
+export type {
+  AnyPlugin,
+  EveryPlugin,
+  InitializedPlugin,
+  LoadedPlugin,
+  PluginClientType,
+  PluginConfigInput,
+  PluginContext,
+  PluginContract,
+  PluginInstance,
+  PluginMetadata,
+  PluginRegistry,
+  PluginRouterType,
+  PluginRuntimeConfig,
+  PluginSecrets,
+  PluginVariables,
+  RegisteredPlugins,
+  SecretsConfig,
+} from "./types";

package/src/orpc-client.ts

@@ -0,0 +1,2 @@
+export * from "@orpc/client";
+export * from "@orpc/react-query";

package/src/orpc-openapi.ts

@@ -0,0 +1,2 @@
+export * from "@orpc/openapi";
+export * from "@orpc/zod";

package/src/orpc.ts

@@ -0,0 +1,9 @@
+export * from "@orpc/contract";
+export * from "@orpc/experimental-publisher";
+export type { IORedisPublisherOptions } from "@orpc/experimental-publisher/ioredis";
+export { IORedisPublisher } from "@orpc/experimental-publisher/ioredis";
+export type { MemoryPublisherOptions } from "@orpc/experimental-publisher/memory";
+export { MemoryPublisher } from "@orpc/experimental-publisher/memory";
+export type { UpstashRedisPublisherOptions } from "@orpc/experimental-publisher/upstash-redis";
+export { UpstashRedisPublisher } from "@orpc/experimental-publisher/upstash-redis";
+export * from "@orpc/server";

package/src/plugin.ts

@@ -0,0 +1,220 @@
+import type { AnyContractRouter, AnySchema, InferSchemaOutput } from "@orpc/contract";
+import { ORPCError } from "@orpc/contract";
+import type { Context, Implementer, Router } from "@orpc/server";
+import { implement, onError } from "@orpc/server";
+import { Effect, type Scope } from "effect";
+import { extractFromFiberFailure, formatORPCError } from "./runtime/errors";
+
+type ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;
+
+export type PluginConfigFor<
+  V extends AnySchema,
+  S extends AnySchema,
+  TRequestContext extends AnySchema | undefined,
+> = {
+  variables: V;
+  secrets: S;
+  context: TRequestContext;
+};
+
+type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+  variables: InferSchemaOutput<V>;
+  secrets: InferSchemaOutput<S>;
+};
+
+type PluginDefinition<
+  V extends AnySchema,
+  S extends AnySchema,
+  TContract extends AnyContractRouter,
+  TRequestContext extends AnySchema | undefined,
+  TDeps extends Context,
+  P extends Record<string, unknown>,
+> = {
+  variables: V;
+  secrets: S;
+  contract: TContract;
+  context?: TRequestContext;
+  initialize?: (
+    config: PluginInitializeInput<V, S>,
+    plugins: P,
+  ) => Effect.Effect<TDeps, Error, Scope.Scope>;
+  createRouter: (
+    deps: TDeps,
+    builder: Implementer<TContract, ContextOutput<TRequestContext>, ContextOutput<TRequestContext>>,
+  ) => Router<TContract, any>;
+  shutdown?: (deps: TDeps) => Effect.Effect<void, Error, never>;
+};
+
+/**
+ * Loaded plugin with static binding property
+ */
+export interface LoadedPluginWithBinding<
+  TContract extends AnyContractRouter,
+  TVariables extends AnySchema,
+  TSecrets extends AnySchema,
+  TRequestContext extends AnySchema | undefined,
+  TDeps extends Context = Record<never, never>,
+> {
+  new (): Plugin<TContract, TVariables, TSecrets, TRequestContext, TDeps>;
+  binding: {
+    contract: TContract;
+    variables: TVariables;
+    secrets: TSecrets;
+    context: TRequestContext;
+  };
+}
+
+/**
+ * Plugin interface
+ */
+export interface Plugin<
+  TContract extends AnyContractRouter,
+  TVariables extends AnySchema,
+  TSecrets extends AnySchema,
+  TRequestContext extends AnySchema | undefined,
+  TDeps extends Context = Record<never, never>,
+> {
+  readonly id: string;
+  readonly contract: TContract;
+  readonly configSchema: PluginConfigFor<TVariables, TSecrets, TRequestContext>;
+
+  initialize(
+    config: PluginInitializeInput<TVariables, TSecrets>,
+    plugins: Record<string, unknown>,
+  ): Effect.Effect<TDeps, unknown, Scope.Scope>;
+
+  shutdown(): Effect.Effect<void, never>;
+
+  /**
+   * 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
+   * @returns A router with procedures matching the plugin's contract
+   */
+  createRouter(deps: TDeps): Router<TContract, any>;
+}
+
+export interface CreatePluginFn {
+  <
+    V extends AnySchema,
+    S extends AnySchema,
+    TContract extends AnyContractRouter,
+    TRequestContext extends AnySchema | undefined = undefined,
+    TDeps extends Context = 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>;
+
+  withPlugins: <P extends Record<string, unknown>>() => CreatePluginWithPlugins<P>;
+}
+
+export const createPlugin: CreatePluginFn = function createPlugin<
+  V extends AnySchema,
+  S extends AnySchema,
+  TContract extends AnyContractRouter,
+  TRequestContext extends AnySchema | undefined = undefined,
+  TDeps extends Context = Record<never, never>,
+  P extends Record<string, unknown> = Record<string, never>,
+>(config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, 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> {
+    /** set during instantiation - registry key */
+    id!: string;
+    readonly contract = config.contract;
+    readonly configSchema = configSchema;
+
+    private _deps: TDeps | null = null;
+
+    initialize(
+      pluginConfig: PluginInitializeInput<V, S>,
+      plugins: Record<string, unknown> = {},
+    ): Effect.Effect<TDeps, unknown, Scope.Scope> {
+      const init = config.initialize ?? (() => Effect.succeed({} as TDeps));
+
+      return init(pluginConfig, plugins as P).pipe(
+        Effect.tap((deps) =>
+          Effect.sync(() => {
+            this._deps = deps;
+          }),
+        ),
+        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(() => Effect.void));
+        }
+      });
+    }
+
+    createRouter(deps: TDeps): Router<TContract, any> {
+      const base = implement(config.contract).$context<ContextOutput<TRequestContext>>();
+      const builder = (base as any).use(
+        onError((error: unknown) => {
+          const unwrapped = extractFromFiberFailure(error);
+
+          if (unwrapped !== error && unwrapped instanceof ORPCError) {
+            throw unwrapped;
+          }
+
+          formatORPCError(error);
+        }),
+      );
+      const router = config.createRouter(deps, builder as any);
+      return router as Router<TContract, any>;
+    }
+  }
+
+  const PluginConstructor = CreatedPlugin as unknown as {
+    new (): Plugin<TContract, V, S, TRequestContext, TDeps>;
+    binding: {
+      contract: TContract;
+      variables: V;
+      secrets: S;
+      context: TRequestContext;
+    };
+  };
+
+  PluginConstructor.binding = {
+    contract: config.contract,
+    variables: config.variables,
+    secrets: config.secrets,
+    context: config.context as TRequestContext,
+  };
+
+  return PluginConstructor as LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+};
+
+export type CreatePluginWithPlugins<P extends Record<string, unknown>> = <
+  V extends AnySchema,
+  S extends AnySchema,
+  TContract extends AnyContractRouter,
+  TRequestContext extends AnySchema | undefined = undefined,
+  TDeps extends Context = Record<never, never>,
+>(
+  config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
+) => LoadedPluginWithBinding<TContract, V, S, TRequestContext, TDeps>;
+
+export function withPlugins<P extends Record<string, unknown>>(): CreatePluginWithPlugins<P> {
+  return <
+    V extends AnySchema,
+    S extends AnySchema,
+    TContract extends AnyContractRouter,
+    TRequestContext extends AnySchema | undefined = undefined,
+    TDeps extends Context = Record<never, never>,
+  >(
+    config: PluginDefinition<V, S, TContract, TRequestContext, TDeps, P>,
+  ) => createPlugin<V, S, TContract, TRequestContext, TDeps, P>(config as any);
+}
+
+createPlugin.withPlugins = withPlugins;