alepha 0.15.1 → 0.15.3

package/src/react/router/providers/ReactServerProvider.ts

@@ -0,0 +1,487 @@
+import { join } from "node:path";
+import {
+  $atom,
+  $env,
+  $hook,
+  $inject,
+  $use,
+  Alepha,
+  type Static,
+  t,
+} from "alepha";
+import { $logger } from "alepha/logger";
+import { ServerHeadProvider } from "alepha/react/head";
+import { type ServerHandler, ServerRouterProvider } from "alepha/server";
+import { ServerLinksProvider } from "alepha/server/links";
+import { ServerStaticProvider } from "alepha/server/static";
+import { FileSystemProvider } from "alepha/system";
+import { renderToReadableStream } from "react-dom/server";
+import { Redirection } from "../errors/Redirection.ts";
+import {
+  $page,
+  type PagePrimitiveRenderOptions,
+  type PagePrimitiveRenderResult,
+} from "../primitives/$page.ts";
+import {
+  type PageRoute,
+  ReactPageProvider,
+  type ReactRouterState,
+} from "./ReactPageProvider.ts";
+import { ReactServerTemplateProvider } from "./ReactServerTemplateProvider.ts";
+import { SSRManifestProvider } from "./SSRManifestProvider.ts";
+
+/**
+ * React server provider responsible for SSR and static file serving.
+ *
+ * Coordinates between:
+ * - ReactPageProvider: Page routing and layer resolution
+ * - ReactServerTemplateProvider: HTML template parsing and streaming
+ * - ServerHeadProvider: Head content management
+ * - SSRManifestProvider: Module preload link collection
+ *
+ * Uses `react-dom/server` under the hood.
+ */
+export class ReactServerProvider {
+  /**
+   * SSR response headers - pre-allocated to avoid object creation per request.
+   */
+  protected readonly SSR_HEADERS = {
+    "content-type": "text/html",
+    "cache-control": "no-store, no-cache, must-revalidate, proxy-revalidate",
+    pragma: "no-cache",
+    expires: "0",
+  } as const;
+
+  protected readonly fs = $inject(FileSystemProvider);
+  protected readonly log = $logger();
+  protected readonly alepha = $inject(Alepha);
+  protected readonly env = $env(envSchema);
+  protected readonly pageApi = $inject(ReactPageProvider);
+  protected readonly templateProvider = $inject(ReactServerTemplateProvider);
+  protected readonly serverHeadProvider = $inject(ServerHeadProvider);
+  protected readonly serverStaticProvider = $inject(ServerStaticProvider);
+  protected readonly serverRouterProvider = $inject(ServerRouterProvider);
+  protected readonly ssrManifestProvider = $inject(SSRManifestProvider);
+
+  /**
+   * Cached check for ServerLinksProvider - avoids has() lookup per request.
+   */
+  protected hasServerLinksProvider = false;
+
+  protected readonly options = $use(reactServerOptions);
+
+  /**
+   * Configure the React server provider.
+   */
+  public readonly onConfigure = $hook({
+    on: "configure",
+    handler: async () => {
+      const pages = this.alepha.primitives($page);
+
+      const ssrEnabled =
+        pages.length > 0 && this.env.REACT_SSR_ENABLED !== false;
+
+      this.alepha.store.set("alepha.react.server.ssr", ssrEnabled);
+
+      // production mode
+      let root = "";
+
+      // non-serverless mode only -> serve static files
+      if (!this.alepha.isServerless() && !this.alepha.isViteDev()) {
+        root = await this.getPublicDirectory();
+        if (!root) {
+          this.log.warn(
+            "Missing static files, static file server will be disabled",
+          );
+        } else {
+          this.log.debug(`Using static files from: ${root}`);
+          await this.configureStaticServer(root);
+        }
+      }
+
+      if (ssrEnabled) {
+        this.registerPages();
+        this.log.info("SSR OK");
+        return;
+      }
+
+      // no SSR enabled, serve a minimal fallback
+      this.log.info("SSR is disabled");
+    },
+  });
+
+  /**
+   * Register all pages as server routes.
+   */
+  protected registerPages(): void {
+    // Set up early head content (entry assets)
+    this.setupEarlyHeadContent();
+
+    // Cache ServerLinksProvider check at startup
+    this.hasServerLinksProvider = this.alepha.has(ServerLinksProvider);
+
+    for (const page of this.pageApi.getPages()) {
+      if (page.component || page.lazy) {
+        this.log.debug(`+ ${page.match} -> ${page.name}`);
+
+        this.serverRouterProvider.createRoute({
+          ...page,
+          schema: undefined, // schema is handled by the page primitive provider
+          method: "GET",
+          path: page.match,
+          handler: this.createHandler(page),
+        });
+      }
+    }
+  }
+
+  /**
+   * Set up early head content with entry assets.
+   *
+   * This content is sent immediately when streaming starts, before page loaders run,
+   * allowing the browser to start downloading entry.js and CSS files early.
+   */
+  protected setupEarlyHeadContent(): void {
+    const assets = this.ssrManifestProvider.getEntryAssets();
+    const globalHead = this.serverHeadProvider.resolveGlobalHead();
+
+    const parts: string[] = [];
+
+    if (assets) {
+      for (const css of assets.css) {
+        parts.push(`<link rel="stylesheet" href="${css}" crossorigin="">`);
+      }
+      if (assets.js) {
+        parts.push(
+          `<script type="module" crossorigin="" src="${assets.js}"></script>`,
+        );
+      }
+    }
+
+    this.templateProvider.setEarlyHeadContent(
+      parts.length > 0 ? `${parts.join("\n")}\n` : "",
+      globalHead,
+    );
+
+    this.log.debug("Early head content set", {
+      css: assets?.css.length ?? 0,
+      js: assets?.js ? 1 : 0,
+    });
+  }
+
+  /**
+   * Get the public directory path where static files are located.
+   */
+  protected async getPublicDirectory(): Promise<string> {
+    const maybe = [
+      join(process.cwd(), `dist/${this.options.publicDir}`),
+      join(process.cwd(), this.options.publicDir),
+    ];
+
+    for (const it of maybe) {
+      if (await this.fs.exists(it)) {
+        return it;
+      }
+    }
+
+    return "";
+  }
+
+  /**
+   * Configure the static file server to serve files from the given root directory.
+   */
+  protected async configureStaticServer(root: string) {
+    await this.serverStaticProvider.createStaticServer({
+      root,
+      cacheControl: {
+        maxAge: 3600,
+        immutable: true,
+      },
+      ...this.options.staticServer,
+    });
+  }
+
+  /**
+   * Create the request handler for a page route.
+   */
+  protected createHandler(route: PageRoute): ServerHandler {
+    return async (serverRequest) => {
+      const { url, reply, query, params } = serverRequest;
+
+      this.log.trace("Rendering page", { name: route.name });
+
+      // Initialize router state
+      const state: ReactRouterState = {
+        url,
+        params,
+        query,
+        name: route.name,
+        onError: () => null,
+        layers: [],
+        meta: {},
+        head: {},
+      };
+
+      // Set up API links if available
+      if (this.hasServerLinksProvider) {
+        this.alepha.store.set(
+          "alepha.server.request.apiLinks",
+          await this.alepha.inject(ServerLinksProvider).getUserApiLinks({
+            user: (serverRequest as any).user, // TODO: fix type
+            authorization: serverRequest.headers.authorization,
+          }),
+        );
+      }
+
+      // Check access permissions
+      let target: PageRoute | undefined = route;
+      while (target) {
+        if (route.can && !route.can()) {
+          this.log.warn(
+            `Access to page '${route.name}' is forbidden by can() check`,
+          );
+          reply.status = 403;
+          reply.headers["content-type"] = "text/plain";
+          return "Forbidden";
+        }
+        target = target.parent;
+      }
+
+      await this.alepha.events.emit("react:server:render:begin", {
+        request: serverRequest,
+        state,
+      });
+
+      // Apply SSR headers early
+      Object.assign(reply.headers, this.SSR_HEADERS);
+
+      // Resolve global head for early streaming (htmlAttributes only)
+      const globalHead = this.serverHeadProvider.resolveGlobalHead();
+
+      // Create optimized HTML stream with early head
+      const htmlStream = this.templateProvider.createEarlyHtmlStream(
+        globalHead,
+        async () => {
+          // === ASYNC WORK (runs while early head is being sent) ===
+          const result = await this.renderPage(route, state);
+
+          if (result.redirect) {
+            // Return redirect URL - template provider will inject meta refresh
+            // since HTTP headers have already been sent
+            return { redirect: result.redirect };
+          }
+
+          return { state, reactStream: result.reactStream! };
+        },
+        {
+          hydration: true,
+          onError: (error) => {
+            if (error instanceof Redirection) {
+              this.log.debug("Streaming resulted in redirection", {
+                redirect: error.redirect,
+              });
+              // Can't do redirect after streaming started - already handled above
+            } else {
+              // disable logging here, it's noisy and duplicate
+              // this.log.error("HTML stream error", error);
+            }
+          },
+        },
+      );
+
+      this.log.trace("Page streaming started (early head optimization)");
+      route.onServerResponse?.(serverRequest);
+      reply.body = htmlStream;
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Core rendering logic - shared between SSR handler and static prerendering
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Core page rendering logic shared between SSR handler and static prerendering.
+   *
+   * Handles:
+   * - Layer resolution (loaders)
+   * - Redirect detection
+   * - Head content filling
+   * - Preload link collection
+   * - React stream rendering
+   *
+   * @param route - The page route to render
+   * @param state - The router state
+   * @returns Render result with redirect or React stream
+   */
+  protected async renderPage(
+    route: PageRoute,
+    state: ReactRouterState,
+  ): Promise<{ redirect?: string; reactStream?: ReadableStream<Uint8Array> }> {
+    // Resolve page layers (loaders)
+    const { redirect } = await this.pageApi.createLayers(route, state);
+    if (redirect) {
+      this.log.debug("Resolver resulted in redirection", { redirect });
+      return { redirect };
+    }
+
+    // Fill head from route config
+    this.serverHeadProvider.fillHead(state);
+
+    // Collect and inject modulepreload links for page-specific chunks
+    const preloadLinks = this.ssrManifestProvider.collectPreloadLinks(route);
+    if (preloadLinks.length > 0) {
+      state.head ??= {};
+      state.head.link = [...(state.head.link ?? []), ...preloadLinks];
+    }
+
+    // Render React to stream
+
+    const element = this.pageApi.root(state);
+    this.alepha.store.set("alepha.react.router.state", state);
+
+    const reactStream = await renderToReadableStream(element, {
+      onError: (error: unknown) => {
+        if (error instanceof Redirection) {
+          this.log.warn("Redirect during streaming ignored", {
+            redirect: error.redirect,
+          });
+        } else {
+          // disable logging here, it's noisy and duplicate
+          // this.log.error("Streaming render error", error);
+        }
+      },
+    });
+
+    return { reactStream };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Testing utilities - kept for backwards compatibility with tests
+  // ---------------------------------------------------------------------------
+
+  /**
+   * For testing purposes, renders a page to HTML string.
+   * Uses the same streaming code path as production, then collects to string.
+   *
+   * @param name - Page name to render
+   * @param options - Render options (params, query, html, hydration)
+   */
+  public async render(
+    name: string,
+    options: PagePrimitiveRenderOptions = {},
+  ): Promise<PagePrimitiveRenderResult> {
+    const page = this.pageApi.page(name);
+    const url = new URL(this.pageApi.url(name, options));
+    const state: ReactRouterState = {
+      url,
+      params: options.params ?? {},
+      query: options.query ?? {},
+      onError: () => null,
+      layers: [],
+      meta: {},
+      head: {},
+    };
+
+    this.log.trace("Rendering", { url });
+
+    await this.alepha.events.emit("react:server:render:begin", { state });
+
+    // Use shared rendering logic
+    const result = await this.renderPage(page, state);
+
+    if (result.redirect) {
+      return { state, html: "", redirect: result.redirect };
+    }
+
+    const reactStream = result.reactStream!;
+
+    // If full HTML page not requested, collect just the React content
+    if (!options.html) {
+      const html = await this.streamToString(reactStream);
+      return { state, html };
+    }
+
+    // Create full HTML stream and collect to string
+    const htmlStream = this.templateProvider.createHtmlStream(
+      reactStream,
+      state,
+      { hydration: options.hydration ?? true },
+    );
+
+    const html = await this.streamToString(htmlStream);
+
+    await this.alepha.events.emit("react:server:render:end", { state, html });
+
+    return { state, html };
+  }
+
+  /**
+   * Collect a ReadableStream into a string.
+   */
+  protected async streamToString(
+    stream: ReadableStream<Uint8Array>,
+  ): Promise<string> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    const chunks: string[] = [];
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(decoder.decode(value, { stream: true }));
+      }
+      chunks.push(decoder.decode()); // Flush remaining
+    } finally {
+      reader.releaseLock();
+    }
+
+    return chunks.join("");
+  }
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+const envSchema = t.object({
+  REACT_SSR_ENABLED: t.optional(t.boolean()),
+});
+
+declare module "alepha" {
+  interface Env extends Partial<Static<typeof envSchema>> {}
+  interface State {
+    "alepha.react.server.ssr"?: boolean;
+  }
+}
+
+/**
+ * React server provider configuration atom
+ */
+export const reactServerOptions = $atom({
+  name: "alepha.react.server.options",
+  schema: t.object({
+    publicDir: t.string(),
+    staticServer: t.object({
+      disabled: t.boolean(),
+      path: t.string({
+        description: "URL path where static files will be served.",
+      }),
+    }),
+  }),
+  default: {
+    publicDir: "public",
+    staticServer: {
+      disabled: false,
+      path: "/",
+    },
+  },
+});
+
+export type ReactServerProviderOptions = Static<
+  typeof reactServerOptions.schema
+>;
+
+declare module "alepha" {
+  interface State {
+    [reactServerOptions.key]: ReactServerProviderOptions;
+  }
+}

package/src/react/router/providers/ReactServerTemplateProvider.spec.ts

@@ -0,0 +1,210 @@
+import { Alepha } from "alepha";
+import { $head } from "alepha/react/head";
+import { HttpClient, ServerProvider } from "alepha/server";
+import { describe, it } from "vitest";
+import { ssrManifestAtom } from "../atoms/ssrManifestAtom.ts";
+import { $page } from "../index.ts";
+
+describe("ReactServerTemplateProvider", () => {
+  describe("streaming", () => {
+    class App {
+      head = $head({
+        htmlAttributes: { lang: "en" },
+      });
+
+      home = $page({
+        path: "/",
+        head: {
+          title: "Test Page",
+          meta: [{ name: "description", content: "Test description" }],
+        },
+        component: () => "Hello World",
+      });
+
+      withLoader = $page({
+        path: "/with-loader",
+        head: { title: "Loader Page" },
+        loader: async () => ({ data: "loaded" }),
+        component: ({ data }) => `Data: ${data}`,
+      });
+    }
+
+    it("should stream complete HTML document with correct structure", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+      }).with(App);
+
+      await alepha.start();
+
+      const server = alepha.inject(ServerProvider);
+      const http = alepha.inject(HttpClient);
+
+      const response = await http.fetch(`${server.hostname}/`);
+
+      // Verify HTML structure
+      expect(response.data).toContain("<!DOCTYPE html>");
+      expect(response.data).toContain('<html lang="en">');
+      expect(response.data).toContain("<head>");
+      expect(response.data).toContain('<meta charset="UTF-8">');
+      expect(response.data).toContain('<meta name="viewport"');
+      expect(response.data).toContain("<title>Test Page</title>");
+      expect(response.data).toContain(
+        '<meta name="description" content="Test description">',
+      );
+      expect(response.data).toContain("</head>");
+      expect(response.data).toContain("<body>");
+      expect(response.data).toContain('<div id="root">');
+      expect(response.data).toContain("Hello World");
+      expect(response.data).toContain("</div>");
+      expect(response.data).toContain("</body>");
+      expect(response.data).toContain("</html>");
+
+      await alepha.stop();
+    });
+
+    it("should include hydration data when enabled", async ({ expect }) => {
+      const alepha = Alepha.create({
+        env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+      }).with(App);
+
+      await alepha.start();
+
+      const server = alepha.inject(ServerProvider);
+      const http = alepha.inject(HttpClient);
+
+      const response = await http.fetch(`${server.hostname}/with-loader`);
+
+      // Verify hydration script is present
+      expect(response.data).toContain("<script>window.__ssr=");
+      expect(response.data).toContain("</script>");
+
+      // Verify hydration data structure
+      expect(response.data).toMatch(/window\.__ssr=\{.*"layers".*\}/);
+
+      await alepha.stop();
+    });
+
+    it("should include entry assets in head when manifest is available", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+      }).with(App);
+
+      // Set up mock SSR manifest
+      alepha.store.set(ssrManifestAtom, {
+        client: {
+          "src/entry.tsx": {
+            file: "assets/entry.abc123.js",
+            isEntry: true,
+            css: ["assets/style.def456.css"],
+          },
+        },
+      });
+
+      await alepha.start();
+
+      const server = alepha.inject(ServerProvider);
+      const http = alepha.inject(HttpClient);
+
+      const response = await http.fetch(`${server.hostname}/`);
+
+      // Verify entry assets are in the head
+      expect(response.data).toContain(
+        '<link rel="stylesheet" href="/assets/style.def456.css" crossorigin="">',
+      );
+      expect(response.data).toContain(
+        '<script type="module" crossorigin="" src="/assets/entry.abc123.js"></script>',
+      );
+
+      await alepha.stop();
+    });
+
+    it("should handle pages with loaders correctly", async ({ expect }) => {
+      const alepha = Alepha.create({
+        env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+      }).with(App);
+
+      await alepha.start();
+
+      const server = alepha.inject(ServerProvider);
+      const http = alepha.inject(HttpClient);
+
+      const response = await http.fetch(`${server.hostname}/with-loader`);
+
+      // Verify loader data is rendered
+      expect(response.data).toContain("Data: loaded");
+
+      await alepha.stop();
+    });
+
+    it("should set correct content-type header", async ({ expect }) => {
+      const alepha = Alepha.create({
+        env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+      }).with(App);
+
+      await alepha.start();
+
+      const server = alepha.inject(ServerProvider);
+      const http = alepha.inject(HttpClient);
+
+      const response = await http.fetch(`${server.hostname}/`);
+
+      expect(response.headers.get("content-type")).toBe("text/html");
+
+      await alepha.stop();
+    });
+
+    it("should set cache-control headers for SSR responses", async ({
+      expect,
+    }) => {
+      const alepha = Alepha.create({
+        env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+      }).with(App);
+
+      await alepha.start();
+
+      const server = alepha.inject(ServerProvider);
+      const http = alepha.inject(HttpClient);
+
+      const response = await http.fetch(`${server.hostname}/`);
+
+      expect(response.headers.get("cache-control")).toContain("no-store");
+
+      await alepha.stop();
+    });
+  });
+
+  describe("error handling", () => {
+    class ErrorApp {
+      errorPage = $page({
+        path: "/error",
+        loader: async () => {
+          throw new Error("Loader error");
+        },
+        component: () => "Should not render",
+      });
+    }
+
+    it("should render error when loader throws", async ({ expect }) => {
+      const alepha = Alepha.create({
+        env: { LOG_LEVEL: "error", SERVER_PORT: 0 },
+      }).with(ErrorApp);
+
+      await alepha.start();
+
+      const server = alepha.inject(ServerProvider);
+      const http = alepha.inject(HttpClient);
+
+      const response = await http.fetch(`${server.hostname}/error`);
+
+      // Should still return a valid HTML response with error
+      expect(response.data).toContain("<!DOCTYPE html>");
+      expect(response.data).toContain("Loader error");
+
+      await alepha.stop();
+    });
+  });
+});