@useavalon/avalon 0.1.0

package/src/nitro/config.ts

@@ -0,0 +1,483 @@
+/**
+ * Nitro Configuration Module for Avalon
+ *
+ * This module provides configuration interfaces and utilities for integrating
+ * Nitro as Avalon's server runtime. It handles preset configuration, route rules,
+ * and merging Avalon-specific options with Nitro defaults.
+ *
+ * ## Static Asset Handling
+ *
+ * Nitro automatically serves static assets from the `public/` directory at the root path.
+ * The configuration supports:
+ * - `publicAssets`: Configures directories for static file serving
+ * - `routeRules`: Configures cache headers for different asset types
+ * - `staticAssets`: Avalon-specific static asset configuration
+ *
+ * Default route rules for static assets are generated by `createDefaultStaticAssetRouteRules()`:
+ * - `/assets/**`, `/islands/**`, `/chunks/**`: Long cache (1 year, immutable)
+ * - `/*.woff`, `/*.woff2`: Long cache for fonts
+ * - `/*.html`, `/*.css`: Short cache with revalidation
+ * - `/favicon.ico`: Medium cache (1 day)
+ */
+
+import type { ResolvedAvalonConfig } from "../vite-plugin/types.ts";
+
+/**
+ * Cache configuration options for route rules
+ */
+export interface CacheOptions {
+  /** Maximum age in seconds for cache validity */
+  maxAge?: number;
+  /** Maximum age in seconds for stale content */
+  staleMaxAge?: number;
+  /** Enable stale-while-revalidate behavior */
+  swr?: boolean;
+}
+
+/**
+ * Route rule configuration for caching, redirects, proxying, and headers
+ */
+export interface RouteRule {
+  /** Cache configuration or boolean to enable/disable */
+  cache?: CacheOptions | boolean;
+  /** Redirect destination URL */
+  redirect?: string;
+  /** Proxy destination URL */
+  proxy?: string;
+  /** Custom headers to set */
+  headers?: Record<string, string>;
+  /** Enable CORS for this route */
+  cors?: boolean;
+}
+
+/**
+ * Static asset serving configuration
+ */
+export interface StaticAssetsConfig {
+  /**
+   * Directory containing public static assets
+   * @default "public"
+   */
+  publicDir?: string;
+
+  /**
+   * Directory containing compiled build output
+   * @default "dist"
+   */
+  buildDir?: string;
+
+  /**
+   * Enable serving pre-compressed assets (gzip, brotli)
+   * @default true
+   */
+  compression?: boolean;
+
+  /**
+   * Default cache control header for immutable static assets
+   * @default "public, max-age=31536000, immutable"
+   */
+  cacheControl?: string;
+
+  /**
+   * Cache control header for mutable assets (HTML, etc.)
+   * @default "public, max-age=0, must-revalidate"
+   */
+  mutableCacheControl?: string;
+
+  /**
+   * Custom headers to add to all static asset responses
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Avalon-specific Nitro configuration options
+ */
+export interface AvalonNitroConfig {
+  /**
+   * Deployment preset (vercel, cloudflare, deno-deploy, node-server, netlify, etc.)
+   * @default "node-server"
+   */
+  preset?: string;
+
+  /**
+   * Directory containing server routes
+   * @default "server"
+   */
+  serverDir?: string;
+
+  /**
+   * Directory containing pages (overrides Avalon config if set)
+   */
+  pagesDir?: string;
+
+  /**
+   * Enable streaming SSR responses
+   * @default true
+   */
+  streaming?: boolean;
+
+  /**
+   * Route rules for caching, redirects, proxying, and headers
+   * Keys are route patterns (e.g., "/api/**", "/static/**")
+   */
+  routeRules?: Record<string, RouteRule>;
+
+  /**
+   * Runtime configuration accessible via useRuntimeConfig()
+   * Can be overridden by NITRO_ prefixed environment variables
+   */
+  runtimeConfig?: Record<string, unknown>;
+
+  /**
+   * Public runtime configuration (exposed to client)
+   */
+  publicRuntimeConfig?: Record<string, unknown>;
+
+  /**
+   * Static asset serving configuration
+   */
+  staticAssets?: StaticAssetsConfig;
+
+  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
+  compatibilityDate?: string;
+  /** Nitro v3: Dependencies to trace instead of bundle */
+  traceDeps?: string[];
+  /** Nitro v3: Rolldown-specific configuration */
+  rolldownConfig?: Record<string, unknown>;
+  /** Nitro v3: Custom server entry point */
+  serverEntry?: string;
+  /** Nitro v3: Renderer configuration, or false to disable */
+  renderer?: { handler: string } | false;
+  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
+  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
+}
+
+/**
+ * Nitro configuration output structure
+ * This matches the expected NitroConfig interface from nitro/types
+ */
+export interface NitroConfigOutput {
+  /** Deployment preset */
+  preset: string;
+  /** Server directory */
+  serverDir: string;
+  /** Route rules */
+  routeRules: Record<string, RouteRule>;
+  /** Runtime configuration */
+  runtimeConfig: {
+    avalon: AvalonRuntimeConfig;
+    [key: string]: unknown;
+  };
+  /** Public runtime configuration */
+  publicRuntimeConfig?: Record<string, unknown>;
+  /** Renderer configuration, or false to disable */
+  renderer?: {
+    handler: string;
+  } | false;
+  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
+  compatibilityDate?: string;
+  /** Nitro v3: Dependencies to trace instead of bundle */
+  traceDeps?: string[];
+  /** Nitro v3: Rolldown-specific configuration */
+  rolldownConfig?: Record<string, unknown>;
+  /** Nitro v3: Custom server entry point */
+  serverEntry?: string;
+  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
+  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
+  /** Public assets directory */
+  publicAssets?: Array<{
+    dir: string;
+    baseURL?: string;
+    maxAge?: number;
+  }>;
+  /** Server assets configuration */
+  serverAssets?: Array<{
+    baseName: string;
+    dir: string;
+  }>;
+  /** Static assets configuration */
+  staticAssets?: StaticAssetsConfig;
+}
+
+/**
+ * Avalon-specific runtime configuration stored in Nitro's runtimeConfig
+ */
+export interface AvalonRuntimeConfig {
+  /** Enable streaming SSR */
+  streaming: boolean;
+  /** Pages directory path */
+  pagesDir: string;
+  /** Layouts directory path */
+  layoutsDir: string;
+}
+
+/**
+ * Default static assets configuration
+ */
+export const DEFAULT_STATIC_ASSETS_CONFIG: Required<StaticAssetsConfig> = {
+  publicDir: "public",
+  buildDir: "dist",
+  compression: true,
+  cacheControl: "public, max-age=31536000, immutable",
+  mutableCacheControl: "public, max-age=0, must-revalidate",
+  headers: {},
+};
+
+/**
+ * All valid Nitro v3 preset names (underscore convention).
+ */
+export const VALID_V3_PRESETS: string[] = [
+  "node_server",
+  "node_middleware",
+  "vercel",
+  "cloudflare_module",
+  "cloudflare_pages",
+  "deno_deploy",
+  "deno_server",
+  "netlify_functions",
+  "netlify_edge",
+  "aws_lambda",
+  "azure_swa",
+  "firebase_functions",
+  "render_com",
+  "static",
+  "browser",
+];
+
+/**
+ * Validates a preset name against the v3 preset list.
+ * Returns the preset name if valid, throws if unrecognized.
+ *
+ * @param preset - The preset name to validate (must be a v3 name)
+ * @returns The validated v3 preset name
+ * @throws Error if the preset is not recognized
+ */
+export function resolvePresetName(preset: string): string {
+  if (VALID_V3_PRESETS.includes(preset)) return preset;
+  throw new Error(
+    `Unknown Nitro preset: "${preset}". Valid presets: ${VALID_V3_PRESETS.join(", ")}`
+  );
+}
+
+/**
+ * Default Nitro configuration values
+ */
+export const DEFAULT_NITRO_CONFIG: Required<
+  Pick<AvalonNitroConfig, "preset" | "serverDir" | "streaming">
+> = {
+  preset: "node_server",
+  serverDir: "server",
+  streaming: true,
+};
+
+/**
+ * Creates a Nitro configuration from Avalon plugin config and Nitro-specific options
+ *
+ * This function merges Avalon's resolved configuration with Nitro-specific options
+ * to produce a complete Nitro configuration object. Avalon-specific settings are
+ * stored in `runtimeConfig.avalon` for access by handlers.
+ *
+ * @param avalonNitroConfig - Nitro-specific configuration options
+ * @param resolvedAvalonConfig - Resolved Avalon plugin configuration
+ * @returns Complete Nitro configuration object
+ *
+ * @example
+ * ```ts
+ * const nitroConfig = createNitroConfig(
+ *   { preset: 'vercel', streaming: true },
+ *   resolvedAvalonConfig
+ * );
+ * ```
+ */
+export function createNitroConfig(
+  avalonNitroConfig: AvalonNitroConfig,
+  resolvedAvalonConfig: ResolvedAvalonConfig
+): NitroConfigOutput {
+  // Determine final directory paths (Nitro config overrides Avalon config)
+  const pagesDir = avalonNitroConfig.pagesDir ?? resolvedAvalonConfig.pagesDir;
+  const layoutsDir = resolvedAvalonConfig.layoutsDir;
+
+  // Build Avalon runtime config
+  const avalonRuntimeConfig: AvalonRuntimeConfig = {
+    streaming: avalonNitroConfig.streaming ?? DEFAULT_NITRO_CONFIG.streaming,
+    pagesDir,
+    layoutsDir,
+  };
+
+  // Validate that runtimeConfig does not contain a 'nitro' key (reserved in v3)
+  if (avalonNitroConfig.runtimeConfig && "nitro" in avalonNitroConfig.runtimeConfig) {
+    throw new Error(
+      'The "nitro" key in runtimeConfig is reserved by Nitro v3 and cannot be used.'
+    );
+  }
+
+  // Merge user runtime config with Avalon runtime config
+  const runtimeConfig: NitroConfigOutput["runtimeConfig"] = {
+    avalon: avalonRuntimeConfig,
+    ...avalonNitroConfig.runtimeConfig,
+  };
+
+  // Merge static assets config with defaults
+  const staticAssetsConfig: StaticAssetsConfig = {
+    ...DEFAULT_STATIC_ASSETS_CONFIG,
+    ...avalonNitroConfig.staticAssets,
+  };
+
+  // Create default route rules for static assets
+  const defaultStaticRouteRules = createDefaultStaticAssetRouteRules(staticAssetsConfig);
+
+  // Merge user route rules with default static asset rules
+  const routeRules = mergeRouteRules(
+    defaultStaticRouteRules,
+    avalonNitroConfig.routeRules ?? {}
+  );
+
+  // Configure public assets directories
+  const publicAssets: NitroConfigOutput["publicAssets"] = [
+    {
+      dir: staticAssetsConfig.publicDir ?? DEFAULT_STATIC_ASSETS_CONFIG.publicDir,
+      baseURL: "/",
+      maxAge: 0, // Let route rules handle caching
+    },
+  ];
+
+  // Resolve renderer: support explicit false to disable, otherwise use default handler
+  const renderer: NitroConfigOutput["renderer"] =
+    avalonNitroConfig.renderer === false
+      ? false
+      : (avalonNitroConfig.renderer ?? { handler: "./server/renderer.ts" });
+
+  return {
+    preset: resolvePresetName(avalonNitroConfig.preset ?? DEFAULT_NITRO_CONFIG.preset),
+    serverDir: avalonNitroConfig.serverDir ?? DEFAULT_NITRO_CONFIG.serverDir,
+    routeRules,
+    runtimeConfig,
+    publicRuntimeConfig: avalonNitroConfig.publicRuntimeConfig,
+    renderer,
+    compatibilityDate: avalonNitroConfig.compatibilityDate,
+    traceDeps: avalonNitroConfig.traceDeps,
+    rolldownConfig: avalonNitroConfig.rolldownConfig,
+    serverEntry: avalonNitroConfig.serverEntry,
+    compressPublicAssets: avalonNitroConfig.compressPublicAssets,
+    publicAssets,
+    staticAssets: staticAssetsConfig,
+  };
+}
+
+/**
+ * Creates default route rules for static asset caching
+ *
+ * @param config - Static assets configuration
+ * @returns Route rules for static assets
+ */
+export function createDefaultStaticAssetRouteRules(
+  config: StaticAssetsConfig
+): Record<string, RouteRule> {
+  const cacheControl = config.cacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.cacheControl;
+  const mutableCacheControl = config.mutableCacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.mutableCacheControl;
+
+  return {
+    // Immutable assets with hashed filenames (long cache)
+    "/assets/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/islands/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/chunks/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/_nuxt/**": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    // Font files (long cache)
+    "/**/*.woff": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    "/**/*.woff2": {
+      headers: {
+        "Cache-Control": cacheControl,
+        ...config.headers,
+      },
+    },
+    // Mutable assets (short cache with revalidation)
+    "/**/*.html": {
+      headers: {
+        "Cache-Control": mutableCacheControl,
+        ...config.headers,
+      },
+    },
+    // Favicon (medium cache)
+    "/favicon.ico": {
+      headers: {
+        "Cache-Control": "public, max-age=86400",
+        ...config.headers,
+      },
+    },
+    // CSS files in public directory (may be mutable)
+    "/**/*.css": {
+      headers: {
+        "Cache-Control": mutableCacheControl,
+        ...config.headers,
+      },
+    },
+  };
+}
+
+/**
+ * Validates a Nitro preset name against the v3 preset list
+ *
+ * @param preset - The preset name to validate
+ * @returns True if the preset is a known valid v3 preset
+ */
+export function isValidPreset(preset: string): boolean {
+  return VALID_V3_PRESETS.includes(preset);
+}
+
+/**
+ * Merges route rules, with later rules taking precedence
+ *
+ * @param baseRules - Base route rules
+ * @param overrideRules - Override route rules
+ * @returns Merged route rules
+ */
+export function mergeRouteRules(
+  baseRules: Record<string, RouteRule>,
+  overrideRules: Record<string, RouteRule>
+): Record<string, RouteRule> {
+  const merged: Record<string, RouteRule> = { ...baseRules };
+
+  for (const [pattern, rule] of Object.entries(overrideRules)) {
+    if (merged[pattern]) {
+      // Deep merge the rule
+      merged[pattern] = {
+        ...merged[pattern],
+        ...rule,
+        headers: {
+          ...merged[pattern].headers,
+          ...rule.headers,
+        },
+      };
+    } else {
+      merged[pattern] = rule;
+    }
+  }
+
+  return merged;
+}