@uploadista/server 0.0.10 → 0.0.12

package/src/core/plugin-types.ts

@@ -0,0 +1,217 @@
+import type { UploadistaError } from "@uploadista/core";
+import type {
+	CredentialProviderLayer,
+	ExtractLayerServices,
+	Flow,
+	ImageAiPluginLayer,
+	ImagePluginLayer,
+	ZipPluginLayer,
+} from "@uploadista/core/flow";
+import type { Effect, Layer } from "effect";
+import type { z } from "zod";
+
+/**
+ * Utility type to extract all services from a tuple of layers.
+ * Given [Layer<A>, Layer<B>], extracts A | B.
+ *
+ * This is a wrapper around the shared ExtractLayerServices utility from @uploadista/core.
+ *
+ * @deprecated Use ExtractLayerServices from @uploadista/core/flow/types instead.
+ *   This will be removed in a future version.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Utility type for extracting services from any layer tuple
+export type ExtractServicesFromLayers<
+	// biome-ignore lint/suspicious/noExplicitAny: Generic constraint must accept any layer configuration
+	T extends readonly Layer.Layer<any, any, any>[],
+> = ExtractLayerServices<T>;
+
+/**
+ * Known plugin layer types for better type inference.
+ * This union helps TypeScript understand which plugins are available.
+ */
+export type KnownPluginLayer =
+  | ImagePluginLayer
+  | ImageAiPluginLayer
+  | CredentialProviderLayer
+  | ZipPluginLayer;
+
+/**
+ * Type-safe plugin tuple that only accepts known plugin layers.
+ * This provides autocomplete and validation for plugin arrays.
+ */
+export type PluginTuple = readonly KnownPluginLayer[];
+
+/**
+ * Extracts the union of all plugin services from a plugin tuple.
+ *
+ * Uses the shared ExtractLayerServices utility from @uploadista/core for consistency.
+ *
+ * @example
+ * ```typescript
+ * type Plugins = [ImagePluginLayer, ZipPluginLayer];
+ * type Services = PluginServices<Plugins>;
+ * // Services = ImagePlugin | ZipPlugin
+ * ```
+ */
+export type PluginServices<TPlugins extends PluginTuple> =
+	ExtractLayerServices<TPlugins>;
+
+/**
+ * Type-safe flow function that declares its plugin requirements.
+ *
+ * @template TRequirements - Union of plugin services this flow needs
+ *
+ * @example
+ * ```typescript
+ * // Flow that requires ImagePlugin
+ * const myFlow: TypeSafeFlowFunction<ImagePlugin> = (flowId, clientId) =>
+ *   Effect.gen(function* () {
+ *     const imageService = yield* ImagePlugin;
+ *     // ...
+ *   });
+ * ```
+ */
+export type TypeSafeFlowFunction<TRequirements = never> = (
+  flowId: string,
+  clientId: string | null,
+) => Effect.Effect<
+  Flow<z.ZodSchema<unknown>, z.ZodSchema<unknown>, TRequirements>,
+  UploadistaError,
+  TRequirements
+>;
+
+/**
+ * Validates that plugins satisfy flow requirements.
+ *
+ * This type creates a compile-time error if required plugins are missing.
+ * When validation fails, it returns an error object with detailed information
+ * including a human-readable message.
+ *
+ * @template TPlugins - The plugin tuple provided
+ * @template TRequirements - The services required by flows
+ *
+ * @example
+ * ```typescript
+ * // ✅ Valid: ImagePlugin is provided and required
+ * type Valid = ValidatePlugins<[ImagePluginLayer], ImagePlugin>;
+ * // Result: true
+ *
+ * // ❌ Error: ImagePlugin required but not provided
+ * type Invalid = ValidatePlugins<[], ImagePlugin>;
+ * // Result: {
+ * //   __error: "MISSING_REQUIRED_PLUGINS";
+ * //   __message: "Missing required plugins: ...";
+ * //   __required: ImagePlugin;
+ * //   __provided: never;
+ * //   __missing: ImagePlugin;
+ * // }
+ * ```
+ */
+export type ValidatePlugins<
+	TPlugins extends PluginTuple,
+	TRequirements,
+> = TRequirements extends never
+	? true // No requirements, always valid
+	: TRequirements extends PluginServices<TPlugins>
+		? true // All requirements satisfied
+		: {
+				readonly __error: "MISSING_REQUIRED_PLUGINS";
+				readonly __message: "Missing required plugins. Check __missing field for details.";
+				readonly __required: TRequirements;
+				readonly __provided: PluginServices<TPlugins>;
+				readonly __missing: Exclude<TRequirements, PluginServices<TPlugins>>;
+				readonly __hint: "Add the missing plugins to your server configuration's plugins array.";
+			};
+
+/**
+ * Type-safe server configuration with compile-time plugin validation.
+ *
+ * This ensures that all plugins required by flows are actually provided.
+ *
+ * @template TPlugins - Tuple of plugin layers
+ * @template TFlowRequirements - Union of services that flows need
+ *
+ * @example
+ * ```typescript
+ * // ✅ Compiles: ImagePlugin provided and required
+ * const config: TypeSafePluginConfig<
+ *   [ImagePluginLayer],
+ *   ImagePlugin
+ * > = {
+ *   plugins: [sharpImagePlugin],
+ *   flows: (flowId, clientId) => imageFlow
+ * };
+ *
+ * // ❌ Compile error: ImagePlugin required but not provided
+ * const bad: TypeSafePluginConfig<
+ *   [],
+ *   ImagePlugin
+ * > = {
+ *   plugins: [],
+ *   flows: (flowId, clientId) => imageFlow
+ * };
+ * ```
+ */
+export type TypeSafePluginConfig<
+  TPlugins extends PluginTuple,
+  TFlowRequirements,
+> = ValidatePlugins<TPlugins, TFlowRequirements> extends true
+  ? {
+      plugins: TPlugins;
+      flows: TypeSafeFlowFunction<TFlowRequirements>;
+    }
+  : ValidatePlugins<TPlugins, TFlowRequirements>; // Returns error object
+
+/**
+ * Extracts plugin requirements from a flow function type.
+ *
+ * This navigates through the flow function signature to extract the requirements
+ * from the Flow type it returns, excluding UploadServer (provided by runtime).
+ *
+ * @template TFlowFn - The flow function type to extract requirements from
+ *
+ * @example
+ * ```typescript
+ * const myFlow = (flowId: string, clientId: string | null) =>
+ *   Effect.succeed(
+ *     createFlow({ ... }) // Returns Flow<..., ..., ImagePlugin | ZipPlugin>
+ *   );
+ *
+ * type Requirements = ExtractFlowPluginRequirements<typeof myFlow>;
+ * // Requirements = ImagePlugin | ZipPlugin
+ * ```
+ */
+export type ExtractFlowPluginRequirements<
+	TFlowFn extends (
+		flowId: string,
+		clientId: string | null,
+	) => Effect.Effect<unknown, unknown, unknown>,
+> = ReturnType<TFlowFn> extends Effect.Effect<infer TFlow, any, any>
+	? TFlow extends Flow<any, any, infer TRequirements>
+		? Exclude<TRequirements, never> // Exclude UploadServer is handled by FlowPluginRequirements in core
+		: never
+	: never;
+
+/**
+ * Helper type to infer plugin requirements from a flow function.
+ *
+ * @example
+ * ```typescript
+ * const myFlow: TypeSafeFlowFunction<ImagePlugin | ZipPlugin> = ...;
+ * type Requirements = InferFlowRequirements<typeof myFlow>;
+ * // Requirements = ImagePlugin | ZipPlugin
+ * ```
+ */
+export type InferFlowRequirements<T> = T extends TypeSafeFlowFunction<infer R>
+	? R
+	: never;
+
+/**
+ * Converts PluginLayer types to Layer.Layer<any, never, any> for runtime use.
+ * Maintains type safety at compile time while allowing flexible runtime composition.
+ */
+export type RuntimePluginLayers<T extends PluginTuple> = {
+  [K in keyof T]: T[K] extends Layer.Layer<infer S, infer E, infer R>
+    ? Layer.Layer<S, E, R>
+    : never;
+};

package/src/core/plugin-validation.ts

@@ -0,0 +1,319 @@
+/**
+ * Runtime plugin validation utilities.
+ *
+ * This module provides runtime validation to ensure that all plugins required
+ * by flows are actually provided to the server. While Effect-TS will catch
+ * missing dependencies at runtime, this validation provides better error messages
+ * and fails fast during server initialization.
+ *
+ * @module plugin-validation
+ */
+
+import type { PluginLayer } from "@uploadista/core";
+import { Effect } from "effect";
+
+/**
+ * Result of plugin validation.
+ */
+export type PluginValidationResult =
+	| {
+			success: true;
+	  }
+	| {
+			success: false;
+			required: string[];
+			provided: string[];
+			missing: string[];
+			suggestions: Array<{
+				name: string;
+				packageName: string;
+				importStatement: string;
+			}>;
+	  };
+
+/**
+ * Known plugin mapping for generating helpful error messages.
+ *
+ * This maps service identifiers to their package names and variable names
+ * for generating import suggestions.
+ */
+const KNOWN_PLUGINS: Record<
+	string,
+	{ packageName: string; variableName: string }
+> = {
+	ImagePlugin: {
+		packageName: "@uploadista/flow-images-sharp",
+		variableName: "sharpImagePlugin",
+	},
+	ImageAiPlugin: {
+		packageName: "@uploadista/flow-images-replicate",
+		variableName: "replicateImagePlugin",
+	},
+	ZipPlugin: {
+		packageName: "@uploadista/flow-utility-zipjs",
+		variableName: "zipPlugin",
+	},
+	CredentialProvider: {
+		packageName: "@uploadista/core",
+		variableName: "credentialProviderLayer",
+	},
+};
+
+/**
+ * Extracts service identifier from a plugin layer.
+ *
+ * This attempts to identify the service provided by a layer using various
+ * heuristics. The exact implementation depends on how Effect-TS exposes
+ * layer metadata.
+ *
+ * @param layer - The plugin layer to inspect
+ * @returns Service identifier string or null if not identifiable
+ */
+function extractServiceIdentifier(layer: PluginLayer): string | null {
+	// Attempt to extract service identifier from layer
+	// Note: Effect-TS doesn't expose this information in a standard way,
+	// so we use Symbol.toStringTag or constructor name as fallbacks
+
+	try {
+		// Try to get the service tag if available
+		// biome-ignore lint/suspicious/noExplicitAny: Layer introspection requires accessing internal properties
+		const layerAny = layer as any;
+
+		// Check for common patterns in Effect layers
+		if (layerAny._tag) {
+			return layerAny._tag;
+		}
+
+		if (layerAny.constructor?.name) {
+			return layerAny.constructor.name;
+		}
+
+		// Try to extract from the layer's context if available
+		if (layerAny.context?.services) {
+			const services = Array.from(layerAny.context.services.keys());
+			if (services.length > 0) {
+				// biome-ignore lint/suspicious/noExplicitAny: Service introspection requires accessing internal properties
+				const firstService = services[0] as any;
+				if (firstService.key) {
+					return firstService.key;
+				}
+			}
+		}
+
+		return null;
+	} catch {
+		// If we can't extract the identifier, return null
+		return null;
+	}
+}
+
+/**
+ * Extracts service identifiers from an array of plugin layers.
+ *
+ * @param plugins - Array of plugin layers
+ * @returns Array of service identifier strings
+ */
+export function extractServiceIdentifiers(
+	plugins: readonly PluginLayer[],
+): string[] {
+	return plugins
+		.map((plugin) => extractServiceIdentifier(plugin))
+		.filter((id): id is string => id !== null);
+}
+
+/**
+ * Validates that all required plugins are provided.
+ *
+ * This is a runtime validation function that checks if the plugins array
+ * contains all services required by the flows. It's called during server
+ * initialization to provide early, clear error messages.
+ *
+ * Note: This validation is best-effort because we can't reliably extract
+ * requirements from flow functions at runtime without executing them.
+ * The main validation happens via Effect-TS's dependency injection.
+ *
+ * @param config - Validation configuration
+ * @returns Validation result with detailed error information if validation fails
+ *
+ * @example
+ * ```typescript
+ * const result = validatePluginRequirements({
+ *   plugins: [sharpImagePlugin, zipPlugin],
+ *   expectedServices: ['ImagePlugin', 'ZipPlugin']
+ * });
+ *
+ * if (!result.success) {
+ *   console.error('Missing plugins:', result.missing);
+ *   console.error('Suggestions:', result.suggestions);
+ * }
+ * ```
+ */
+export function validatePluginRequirements(config: {
+	plugins: readonly PluginLayer[];
+	expectedServices?: string[];
+}): PluginValidationResult {
+	const { plugins, expectedServices = [] } = config;
+
+	// Extract identifiers from provided plugins
+	const providedServices = extractServiceIdentifiers(plugins);
+
+	// Check for missing services
+	const missing = expectedServices.filter(
+		(required) => !providedServices.includes(required),
+	);
+
+	if (missing.length === 0) {
+		return { success: true };
+	}
+
+	// Generate suggestions for missing plugins
+	const suggestions = missing
+		.map((service) => {
+			const knownPlugin = KNOWN_PLUGINS[service];
+			if (!knownPlugin) {
+				return null;
+			}
+
+			return {
+				name: service,
+				packageName: knownPlugin.packageName,
+				importStatement: `import { ${knownPlugin.variableName} } from '${knownPlugin.packageName}';`,
+			};
+		})
+		.filter((s): s is NonNullable<typeof s> => s !== null);
+
+	return {
+		success: false,
+		required: expectedServices,
+		provided: providedServices,
+		missing,
+		suggestions,
+	};
+}
+
+/**
+ * Creates a formatted error message for plugin validation failures.
+ *
+ * This generates a detailed, human-readable error message that includes:
+ * - List of required plugins
+ * - List of provided plugins
+ * - List of missing plugins
+ * - Import statements for missing plugins (if known)
+ * - Example server configuration
+ *
+ * @param result - Failed validation result
+ * @returns Formatted error message string
+ *
+ * @example
+ * ```typescript
+ * const result = validatePluginRequirements({ ... });
+ * if (!result.success) {
+ *   const message = formatPluginValidationError(result);
+ *   throw new Error(message);
+ * }
+ * ```
+ */
+export function formatPluginValidationError(
+	result: Extract<PluginValidationResult, { success: false }>,
+): string {
+	const lines: string[] = [
+		"Server initialization failed: Missing required plugins",
+		"",
+		`Required: ${result.required.join(", ")}`,
+		`Provided: ${result.provided.length > 0 ? result.provided.join(", ") : "(none)"}`,
+		`Missing:  ${result.missing.join(", ")}`,
+		"",
+	];
+
+	if (result.suggestions.length > 0) {
+		lines.push("Add the missing plugins to your configuration:");
+		lines.push("");
+		for (const suggestion of result.suggestions) {
+			lines.push(`  ${suggestion.importStatement}`);
+		}
+		lines.push("");
+		lines.push("  const server = await createUploadistaServer({");
+		lines.push(
+			`    plugins: [${[...result.provided, ...result.missing.map((m) => KNOWN_PLUGINS[m]?.variableName || m)].join(", ")}],`,
+		);
+		lines.push("    // ...");
+		lines.push("  });");
+	} else {
+		lines.push(
+			"Note: Could not determine package names for missing plugins.",
+		);
+		lines.push("Please ensure all required plugin layers are provided.");
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Effect-based plugin validation that can be composed with other Effects.
+ *
+ * This provides an Effect-TS native way to validate plugins, allowing it
+ * to be composed with other Effects in the server initialization pipeline.
+ *
+ * @param config - Validation configuration
+ * @returns Effect that succeeds if validation passes, fails with UploadistaError if not
+ *
+ * @example
+ * ```typescript
+ * const validatedServer = Effect.gen(function* () {
+ *   yield* validatePluginRequirementsEffect({
+ *     plugins: [sharpImagePlugin],
+ *     expectedServices: ['ImagePlugin', 'ZipPlugin']
+ *   });
+ *
+ *   return yield* createServerEffect(...);
+ * });
+ * ```
+ */
+export function validatePluginRequirementsEffect(config: {
+	plugins: readonly PluginLayer[];
+	expectedServices?: string[];
+}): Effect.Effect<void, Error> {
+	return Effect.sync(() => {
+		const result = validatePluginRequirements(config);
+
+		if (!result.success) {
+			const message = formatPluginValidationError(result);
+			throw new Error(message);
+		}
+	});
+}
+
+/**
+ * Validates plugin configuration at runtime during server initialization.
+ *
+ * This is a convenience function that performs validation and throws a
+ * descriptive error if validation fails. Use this at the beginning of
+ * createUploadistaServer to fail fast with clear error messages.
+ *
+ * @param config - Validation configuration
+ * @throws Error with detailed message if validation fails
+ *
+ * @example
+ * ```typescript
+ * export const createUploadistaServer = async (config) => {
+ *   // Validate plugins early
+ *   validatePluginsOrThrow({
+ *     plugins: config.plugins,
+ *     expectedServices: ['ImagePlugin', 'ZipPlugin']
+ *   });
+ *
+ *   // Continue with server creation...
+ * };
+ * ```
+ */
+export function validatePluginsOrThrow(config: {
+	plugins: readonly PluginLayer[];
+	expectedServices?: string[];
+}): void {
+	const result = validatePluginRequirements(config);
+
+	if (!result.success) {
+		const message = formatPluginValidationError(result);
+		throw new Error(message);
+	}
+}