@moonsjs/vite 0.0.0-stage → 0.1.0

package/src/server/handler.ts

@@ -0,0 +1,249 @@
+import {
+  MoonsError,
+  composeMiddleware,
+  resolveRoute,
+  routeKeyFromFile,
+  runLoaders,
+  type MoonsConfig,
+  type ResolvedRoute,
+  type RouteDefinition,
+  type RouteModule,
+} from "@moonsjs/core";
+import { encodeSsrPayload, reviveError, serializeError } from "@moonsjs/core/serialize";
+import { renderToMarkup } from "@moonsjs/react/ssr";
+import type { ClientRouteEntry, RouteModuleShape } from "@moonsjs/react/internal";
+import { createRpcHandler, runWithContext } from "@moonsjs/server";
+import { ERROR_ROUTE_KEY, NOT_FOUND_ROUTE_KEY } from "../manifest";
+import type { Shell } from "./shell";
+
+const RPC_PREFIX = "/_moons/fn/";
+const HEALTH_PATH = "/_moons/health";
+
+export interface RequestHandlerOptions {
+  routes: RouteDefinition[];
+  /** Config yang sudah divalidasi. */
+  config: MoonsConfig;
+  /** Direktori route absolut; dipakai untuk derivasi key stabil. */
+  routesDir: string;
+  /** Peta import() modul route, key = routeKeyFromFile. */
+  loadRoute: Record<string, () => Promise<RouteModule>>;
+  shell: Shell;
+}
+
+/**
+ * Handler HTML: context → middleware global → resolve route → loader paralel
+ * → render React → inject payload devalue (PRD §11.2, §14.2, §17).
+ */
+export function createRequestHandler(
+  options: RequestHandlerOptions,
+): (request: Request) => Promise<Response> {
+  const { routes, config, routesDir, loadRoute, shell } = options;
+  const rpc = createRpcHandler(
+    config.security === undefined ? {} : { security: config.security },
+  );
+  const notFoundRoute = routes.find((route) => route.kind === "404");
+  const errorRoute = routes.find((route) => route.kind === "error");
+
+  async function renderRoute(
+    resolved: ResolvedRoute,
+    request: Request,
+    ctx: Ctx,
+  ): Promise<Response> {
+    const entries = [...resolved.layouts, resolved.route];
+    const keys = entries.map((entry) => routeKeyFromFile(routesDir, entry.file));
+    const modules = await loadModules(keys, loadRoute);
+
+    const data = await runLoaders(
+      entries.map((entry, index) => ({ file: keys[index] as string, module: modules[index] as RouteModule })),
+      { params: resolved.params, ctx, req: request },
+    );
+
+    const pageKey = routeKeyFromFile(routesDir, resolved.route.file);
+    const pageModule = modules[modules.length - 1] as RouteModule;
+    const entry: ClientRouteEntry = { page: pageKey, layouts: keys.slice(0, -1) };
+    // Addendum A.3: query string ikut ke payload agar server/client identik.
+    const searchParams = Object.fromEntries(new URL(request.url).searchParams);
+
+    const markup = renderToMarkup(
+      entry,
+      { page: pageModule as RouteModuleShape, layouts: modules.slice(0, -1) as RouteModuleShape[] },
+      resolved.params,
+      data,
+      searchParams,
+    );
+    const payload = encodeSsrPayload({
+      key: pageKey,
+      params: resolved.params,
+      searchParams,
+      data,
+    });
+
+    return htmlResponse(await shell(markup, payload, request.url), 200);
+  }
+
+  /** §11.2: halaman `_404.tsx` kustom (standalone), fallback bawaan. */
+  async function notFoundResponse(request: Request): Promise<Response> {
+    if (notFoundRoute !== undefined) {
+      try {
+        const key = routeKeyFromFile(routesDir, notFoundRoute.file);
+        const [module] = await loadModules([key], loadRoute);
+        const payload = encodeSsrPayload({ key: NOT_FOUND_ROUTE_KEY, params: {}, data: {} });
+        const markup = renderToMarkup(
+          { page: key, layouts: [] },
+          { page: module as RouteModuleShape, layouts: [] },
+          {},
+          {},
+        );
+        return htmlResponse(await shell(markup, payload, request.url), 404);
+      } catch (error) {
+        console.error("[moons] gagal merender _404 kustom:", error);
+      }
+    }
+
+    const payload = encodeSsrPayload({ key: "", params: {}, data: {} });
+    const html = await shell(
+      "<h1>404</h1><p>Halaman tidak ditemukan.</p>",
+      payload,
+      request.url,
+    );
+    return htmlResponse(html, 404);
+  }
+
+  /**
+   * §11.2: halaman `_error.tsx` kustom dengan `RouteErrorProvider`.
+   * Production tidak men-serialisasi error apa pun (§16.6); dev mengirim aslinya.
+   */
+  async function routeErrorResponse(error: unknown, request: Request): Promise<Response> {
+    console.error("[moons] route error:", error);
+
+    if (errorRoute !== undefined) {
+      try {
+        const key = routeKeyFromFile(routesDir, errorRoute.file);
+        const [module] = await loadModules([key], loadRoute);
+        const isProduction = process.env["NODE_ENV"] === "production";
+        const serialized = isProduction ? undefined : serializeError(error);
+        const payload = encodeSsrPayload({
+          key: ERROR_ROUTE_KEY,
+          params: {},
+          data: {},
+          ...(serialized === undefined ? {} : { error: serialized }),
+        });
+        const markup = renderToMarkup(
+          { page: key, layouts: [] },
+          { page: module as RouteModuleShape, layouts: [] },
+          {},
+          {},
+          {},
+          serialized === undefined ? undefined : reviveError(serialized),
+        );
+        return htmlResponse(await shell(markup, payload, request.url), 500);
+      } catch (renderError) {
+        console.error("[moons] gagal merender _error kustom:", renderError);
+      }
+    }
+
+    return internalErrorResponse(error, { log: false });
+  }
+
+  return async function handler(request: Request): Promise<Response> {
+    try {
+      const url = new URL(request.url);
+
+      // §19.5: health ditangani paling awal — tetap hidup walau kode user rusak.
+      if (url.pathname === HEALTH_PATH) {
+        return healthResponse(request.method);
+      }
+
+      // `MoonsConfig.context` bertipe `unknown` (menghindari referensi sirkular
+      // ke global `Ctx` — §13); kontraknya tetap `Promise<Ctx>`, jadi cast di
+      // batas runtime ini. Tanpa cast, tsc app user yang memuat `@moonsjs/vite/server`
+      // (mis. `createTestServer` §19.5) melihat `unknown` vs `Ctx` global app.
+      const ctx = (await config.context(request)) as Ctx;
+
+      const respond = composeMiddleware(config.middleware ?? [], ctx, async () => {
+        if (url.pathname.startsWith(RPC_PREFIX)) {
+          return await rpc(request, url.pathname.slice(RPC_PREFIX.length), ctx);
+        }
+        const resolved = resolveRoute(url.pathname, routes);
+        if (resolved === null) {
+          return await notFoundResponse(request);
+        }
+        try {
+          return await renderRoute(resolved, request, ctx);
+        } catch (error) {
+          return await routeErrorResponse(error, request);
+        }
+      });
+
+      return await runWithContext(ctx, () => respond(request));
+    } catch (error) {
+      return internalErrorResponse(error);
+    }
+  };
+}
+
+async function loadModules(
+  keys: string[],
+  loadRoute: Record<string, () => Promise<RouteModule>>,
+): Promise<RouteModule[]> {
+  return await Promise.all(
+    keys.map(async (key) => {
+      const load = loadRoute[key];
+      if (load === undefined) {
+        throw new MoonsError({
+          code: "E_INTERNAL",
+          message: `modul route \`${key}\` tidak terdaftar`,
+          details: "Registry route tidak sinkron dengan hasil scan.",
+          suggestions: ["Jalankan ulang `bun run build`, atau restart dev server"],
+        });
+      }
+      return await load();
+    }),
+  );
+}
+
+function internalErrorResponse(error: unknown, options: { log?: boolean } = {}): Response {
+  if (options.log !== false) {
+    console.error("[moons] request error:", error);
+  }
+
+  const detail =
+    process.env["NODE_ENV"] !== "production" && error instanceof MoonsError
+      ? `<pre>${escapeHtml(error.format())}</pre>`
+      : "<p>Terjadi kesalahan internal.</p>";
+
+  return htmlResponse(
+    `<!doctype html><html lang="id"><head><meta charset="utf-8"><title>500</title></head><body><h1>500</h1>${detail}</body></html>`,
+    500,
+  );
+}
+
+function htmlResponse(html: string, status: number): Response {
+  return new Response(html, {
+    status,
+    headers: { "content-type": "text/html; charset=utf-8" },
+  });
+}
+
+/** §19.5: `/_moons/health` → `{ ok: true }`. */
+function healthResponse(method: string): Response {
+  const headers = { "content-type": "application/json; charset=utf-8" };
+  if (method === "GET" || method === "HEAD") {
+    return new Response(method === "HEAD" ? null : JSON.stringify({ ok: true }), {
+      status: 200,
+      headers,
+    });
+  }
+  return new Response("Method Not Allowed", {
+    status: 405,
+    headers: { allow: "GET, HEAD" },
+  });
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}

package/src/server/index.ts

@@ -0,0 +1,12 @@
+export { createRequestHandler } from "./handler";
+export type { RequestHandlerOptions } from "./handler";
+export { createDevShell, createFileShell, injectShell, DEFAULT_TEMPLATE, ROOT_PLACEHOLDER } from "./shell";
+export type { Shell } from "./shell";
+export { startNodeServer, resolveStaticFile } from "./node-server";
+export type { NodeServerOptions } from "./node-server";
+export { installGracefulShutdown } from "./shutdown";
+export type { ShutdownOptions } from "./shutdown";
+export { createTestServer } from "./test-server";
+export type { TestServer, TestServerOptions } from "./test-server";
+export { sendNodeResponse, toWebRequest } from "./node";
+export { installDevMiddleware } from "./dev";

package/src/server/node-server.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import { extname, join, resolve, sep } from "node:path";
+import { sendNodeResponse, toWebRequest } from "./node";
+import { installGracefulShutdown } from "./shutdown";
+
+const MIME_TYPES: Record<string, string> = {
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+  ".wasm": "application/wasm",
+};
+
+export interface NodeServerOptions {
+  port?: number;
+  clientDir?: string;
+  /** Pasang handler SIGTERM/SIGINT (default true). */
+  handleSignals?: boolean;
+  /** Batas drain shutdown (default 10_000 ms). */
+  shutdownTimeoutMs?: number;
+}
+
+/**
+ * Serve produksi (M1 §19.2, §18): static dari `dist/client` + handler SSR.
+ * Berjalan di Bun dan Node (hanya API `node:*`).
+ */
+export function startNodeServer(
+  handler: (request: Request) => Promise<Response>,
+  options: NodeServerOptions = {},
+): Server {
+  const clientDir = resolve(options.clientDir ?? join(process.cwd(), "dist/client"));
+  const port = options.port ?? Number(process.env["PORT"] ?? 3000);
+
+  const server = createServer((req, res) => {
+    void (async () => {
+      try {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+        if (req.method === "GET" || req.method === "HEAD") {
+          const staticFile = resolveStaticFile(clientDir, url.pathname);
+          if (staticFile !== null) {
+            const body = readFileSync(staticFile);
+            res.statusCode = 200;
+            res.setHeader("content-type", MIME_TYPES[extname(staticFile).toLowerCase()] ?? "application/octet-stream");
+            res.end(req.method === "HEAD" ? undefined : body);
+            return;
+          }
+        }
+
+        const response = await handler(await toWebRequest(req));
+        await sendNodeResponse(res, response);
+      } catch (error) {
+        console.error("[moons] server error:", error);
+        res.statusCode = 500;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("Internal Server Error");
+      }
+    })();
+  });
+
+  server.listen(port, () => {
+    const address = server.address();
+    const boundPort = typeof address === "object" && address !== null ? address.port : port;
+    console.log(`[moons] server listening on http://localhost:${boundPort}`);
+  });
+
+  if (options.handleSignals !== false) {
+    const shutdown = installGracefulShutdown(
+      server,
+      options.shutdownTimeoutMs === undefined ? {} : { timeoutMs: options.shutdownTimeoutMs },
+    );
+    // `once`: sinyal kedua memakai perilaku default (proses langsung berhenti).
+    process.once("SIGTERM", () => shutdown("SIGTERM"));
+    process.once("SIGINT", () => shutdown("SIGINT"));
+  }
+
+  return server;
+}
+
+/** Resolve file static dengan proteksi path traversal. */
+export function resolveStaticFile(clientDir: string, pathname: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+
+  const candidate = resolve(clientDir, `.${decoded}`);
+  if (candidate !== clientDir && !candidate.startsWith(clientDir + sep)) {
+    return null;
+  }
+  if (!existsSync(candidate)) {
+    return null;
+  }
+  if (!statSync(candidate).isFile()) {
+    return null;
+  }
+  return candidate;
+}

package/src/server/node.ts

@@ -0,0 +1,61 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+const MAX_BODY_BYTES = 32 * 1024 * 1024; // batas defensif transport; limit RPC §7.3 tetap berlaku
+
+/** Konversi request Node → Web `Request` (body diteruskan untuk non-GET/HEAD, §7.3). */
+export async function toWebRequest(req: IncomingMessage): Promise<Request> {
+  const host = req.headers.host ?? "localhost";
+  const url = `http://${host}${req.url ?? "/"}`;
+  const method = req.method ?? "GET";
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined || key === "content-length") {
+      // content-length tidak disalin; fetch menghitung ulang dari body.
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        headers.append(key, item);
+      }
+    } else {
+      headers.set(key, value);
+    }
+  }
+
+  if (method === "GET" || method === "HEAD") {
+    return new Request(url, { method, headers });
+  }
+
+  const body = await readBody(req);
+  return new Request(url, { method, headers, body: new Uint8Array(body) });
+}
+
+function readBody(req: IncomingMessage): Promise<Buffer> {
+  return new Promise((resolvePromise, reject) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+
+    req.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_BODY_BYTES) {
+        req.destroy();
+        reject(new Error("request body melebihi batas transport"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => resolvePromise(Buffer.concat(chunks)));
+    req.on("error", (error) => reject(error));
+  });
+}
+
+/** Tulis Web `Response` ke `ServerResponse` Node. */
+export async function sendNodeResponse(res: ServerResponse, response: Response): Promise<void> {
+  res.statusCode = response.status;
+  response.headers.forEach((value, key) => {
+    res.setHeader(key, value);
+  });
+  const body = Buffer.from(await response.arrayBuffer());
+  res.end(body);
+}

package/src/server/shell.ts

@@ -0,0 +1,77 @@
+import { MoonsError } from "@moonsjs/core";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ViteDevServer } from "vite";
+
+export type Shell = (markup: string, payload: string, url: string) => string | Promise<string>;
+
+export const ROOT_PLACEHOLDER = '<div id="root"></div>';
+
+export const DEFAULT_TEMPLATE = [
+  "<!doctype html>",
+  '<html lang="id">',
+  "<head>",
+  '  <meta charset="utf-8" />',
+  '  <meta name="viewport" content="width=device-width, initial-scale=1" />',
+  "  <title>Moons</title>",
+  "</head>",
+  "<body>",
+  `  ${ROOT_PLACEHOLDER}`,
+  '  <script type="module" src="/src/client/main.tsx"></script>',
+  "</body>",
+  "</html>",
+  "",
+].join("\n");
+
+/** Inject markup SSR + payload devalue ke shell HTML (PRD §8.2, §17). */
+export function injectShell(template: string, markup: string, payload: string): string {
+  if (!template.includes(ROOT_PLACEHOLDER)) {
+    throw new MoonsError({
+      code: "E_INTERNAL",
+      message: `shell HTML tidak memuat \`${ROOT_PLACEHOLDER}\``,
+      details: "index.html aplikasi wajib memuat elemen root tersebut agar SSR bisa meng-inject markup.",
+      suggestions: [
+        `Tambahkan ${ROOT_PLACEHOLDER} ke index.html`,
+        "Atau hapus index.html untuk memakai shell bawaan",
+      ],
+    });
+  }
+  const dataScript = `<script id="__moons_data" type="application/x-moons">${payload}</script>`;
+  return template.replace(ROOT_PLACEHOLDER, `<div id="root">${markup}</div>${dataScript}`);
+}
+
+/**
+ * Shell untuk dev: baca `index.html` dari disk setiap request (selalu segar)
+ * lalu lewatkan ke Vite `transformIndexHtml` (inject `/@vite/client`, dsb).
+ */
+export function createDevShell(server: ViteDevServer, options: { templatePath: string }): Shell {
+  return async (markup, payload, url) => {
+    const template = existsSync(options.templatePath)
+      ? readFileSync(options.templatePath, "utf8")
+      : DEFAULT_TEMPLATE;
+    const html = injectShell(template, markup, payload);
+    return await server.transformIndexHtml(url, html);
+  };
+}
+
+/** Shell untuk produksi: baca `dist/client/index.html` sekali dari cwd. */
+export function createFileShell(options: { clientDir?: string } = {}): Shell {
+  let cached: string | null = null;
+  return async (markup, payload) => {
+    if (cached === null) {
+      const clientDir = resolve(options.clientDir ?? process.cwd(), "dist/client");
+      const file = join(clientDir, "index.html");
+      if (!existsSync(file)) {
+        throw new MoonsError({
+          code: "E_INTERNAL",
+          file,
+          message: "`dist/client/index.html` tidak ditemukan",
+          details: "Build client harus dijalankan sebelum server produksi dinyalakan (PRD §18).",
+          suggestions: ["Jalankan `bun run build` lebih dulu"],
+        });
+      }
+      cached = readFileSync(file, "utf8");
+    }
+    return injectShell(cached, markup, payload);
+  };
+}

package/src/server/shutdown.ts

@@ -0,0 +1,64 @@
+import type { Server } from "node:http";
+
+export interface ShutdownOptions {
+  /** Batas drain sebelum keluar paksa (default 10_000 ms). */
+  timeoutMs?: number;
+  log?: (message: string) => void;
+  /** Injectable untuk test; default `process.exit`. */
+  exit?: (code: number) => void;
+}
+
+/**
+ * Graceful shutdown (PRD §19.5): SIGTERM/SIGINT → stop menerima koneksi baru →
+ * drain request berjalan → exit 0. Melewati timeout → keluar paksa exit 1.
+ *
+ * Handler dipasang `once` oleh pemanggil, sehingga sinyal kedua memakai
+ * perilaku default (proses langsung berhenti).
+ */
+export function installGracefulShutdown(
+  server: Server,
+  options: ShutdownOptions = {},
+): (signal: NodeJS.Signals) => void {
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const log = options.log ?? ((message: string) => console.log(message));
+  const exit = options.exit ?? ((code: number) => process.exit(code));
+
+  let shuttingDown = false;
+
+  return (signal: NodeJS.Signals): void => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    log(`[moons] menerima ${signal} — berhenti menerima koneksi, drain...`);
+
+    const timer = setTimeout(() => {
+      log(`[moons] drain melewati ${timeoutMs}ms — keluar paksa`);
+      const closeAll = (server as { closeAllConnections?: () => void }).closeAllConnections;
+      try {
+        closeAll?.call(server);
+      } catch {
+        // abaikan: keluar paksa tetap jalan
+      }
+      exit(1);
+    }, timeoutMs);
+    timer.unref?.();
+
+    try {
+      (server as { closeIdleConnections?: () => void }).closeIdleConnections?.();
+    } catch {
+      // abaikan: fallback timeout tetap ada
+    }
+
+    server.close((error?: Error) => {
+      clearTimeout(timer);
+      if (error !== undefined) {
+        log(`[moons] penutupan server gagal: ${error.message}`);
+        exit(1);
+        return;
+      }
+      log("[moons] shutdown selesai (drain penuh)");
+      exit(0);
+    });
+  };
+}

package/src/server/test-server.ts

@@ -0,0 +1,44 @@
+import type { MoonsConfig, RouteDefinition, RouteModule } from "@moonsjs/core";
+import { createRequestHandler } from "./handler";
+import { DEFAULT_TEMPLATE, injectShell, type Shell } from "./shell";
+
+export interface TestServerOptions {
+  routes: RouteDefinition[];
+  config: MoonsConfig;
+  routesDir: string;
+  loadRoute: Record<string, () => Promise<RouteModule>>;
+  /** Default: shell in-memory dari `DEFAULT_TEMPLATE` (tanpa file). */
+  shell?: Shell;
+}
+
+export interface TestServer {
+  handler: (request: Request) => Promise<Response>;
+  /** Dispatch request langsung ke handler — tanpa port/jaringan (§19.5). */
+  fetch(input: string, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Utility test in-process (PRD §19.5): jalankan handler tanpa listen port.
+ * Dipakai test aplikasi user maupun test internal framework.
+ */
+export function createTestServer(
+  options: TestServerOptions,
+  baseUrl = "http://localhost",
+): TestServer {
+  const shell: Shell =
+    options.shell ?? ((markup, payload) => injectShell(DEFAULT_TEMPLATE, markup, payload));
+
+  const handler = createRequestHandler({
+    routes: options.routes,
+    config: options.config,
+    routesDir: options.routesDir,
+    loadRoute: options.loadRoute,
+    shell,
+  });
+
+  return {
+    handler,
+    fetch: (input: string, init?: RequestInit) =>
+      handler(new Request(new URL(input, baseUrl), init)),
+  };
+}