@xacos/server 1.0.0

package/src/XServer.ts

@@ -0,0 +1,172 @@
+import Fastify, { FastifyInstance } from "fastify";
+import type { XApp, XMiddleware } from "@xacos/shared";
+import { mountApiRoutes } from "./routing/mountApiRoutes";
+import cookie from "@fastify/cookie";
+import multipart from "@fastify/multipart";
+import formbody from "@fastify/formbody";
+import cors from "@fastify/cors";
+import rateLimit from "@fastify/rate-limit";
+
+import type { XacosConfig } from "@xacos/config";
+import { log } from "./Logger";
+import { closeDb } from "@xacos/orm";
+import pkg from "../package.json";
+
+let shutdownRegistered = false;
+
+export class XServer {
+  public readonly fastify: FastifyInstance;
+  private readonly globalMiddlewares: XMiddleware[] = [];
+
+  constructor() {
+    const isDev = process.env["APP_ENV"] !== "production";
+    this.fastify = Fastify({
+      bodyLimit: 10 * 1024 * 1024, // 10MB max body size
+      logger: {
+        level: process.env["APP_DEBUG"] === "true" || isDev ? "debug" : "info",
+        transport: isDev
+          ? {
+            target: "pino-pretty",
+            options: {
+              translateTime: "HH:MM:ss Z",
+              ignore: "pid,hostname",
+            },
+          }
+          : undefined,
+      } as any,
+    });
+
+    this.fastify.addHook('onSend', async (_request, reply) => {
+      reply.header('X-Content-Type-Options', 'nosniff');
+      reply.header('X-Frame-Options', 'SAMEORIGIN');
+      reply.header('X-XSS-Protection', '1; mode=block');
+      reply.header('Referrer-Policy', 'strict-origin-when-cross-origin');
+      if (process.env['APP_ENV'] === 'production') {
+        reply.header('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');
+      }
+    });
+
+    void this.fastify.register(cookie as any);
+    void this.fastify.register(formbody as any);
+    const metaSym = Symbol.for('plugin-meta');
+    if ((multipart as any)[metaSym]) {
+      (multipart as any)[metaSym].fastify = '4.x';
+    }
+    void this.fastify.register(multipart as any, {
+      limits: {
+        fileSize: 10 * 1024 * 1024, // 10MB default
+      },
+    });
+
+    this.setupErrorHandler();
+    this.setupHealthCheck();
+  }
+
+  private setupHealthCheck() {
+    this.fastify.get("/health", async (_req, reply) => {
+      return reply.send({
+        status: "ok",
+        uptime: process.uptime(),
+        memory: process.memoryUsage(),
+        version: pkg.version,
+        env: process.env["APP_ENV"] ?? "development",
+      });
+    });
+  }
+
+  async bootstrap(config: XacosConfig): Promise<void> {
+    // ── CORS ────────────────────────────────────────────────────────────────
+    await this.fastify.register(cors as any, {
+      origin: config.cors?.origin ?? true,
+      credentials: config.cors?.credentials ?? true,
+      methods: config.cors?.methods ?? ["GET", "POST", "PUT", "DELETE", "PATCH"],
+    });
+
+    // ── Rate Limit ──────────────────────────────────────────────────────────
+    await this.fastify.register(rateLimit as any, {
+      max: config.rateLimit?.max ?? 100,
+      timeWindow: config.rateLimit?.timeWindow ?? "1 minute",
+    });
+  }
+
+  private setupErrorHandler() {
+    this.fastify.setErrorHandler((error, request, reply) => {
+      const statusCode = error.statusCode ?? 500;
+      const isDev = process.env["APP_ENV"] !== "production";
+
+      let code = (error as any).code;
+      if (!code) {
+        if (statusCode === 422 || error.name === "ValidationError") code = "VALIDATION_FAILED";
+        else if (statusCode === 404) code = "NOT_FOUND";
+        else if (statusCode === 401) code = "UNAUTHORIZED";
+        else if (statusCode === 403) code = "FORBIDDEN";
+        else if (statusCode === 400) code = "BAD_REQUEST";
+        else code = "INTERNAL_ERROR";
+      }
+
+      // Structured logging via Pino per error
+      log.error(`[XServer Error] ${error.message}`, {
+        url: request.url,
+        method: request.method,
+        statusCode,
+        code,
+        stack: isDev ? error.stack : undefined,
+      });
+
+      request.log.error(error);
+
+      void reply.status(statusCode).send({
+        success: false,
+        error: {
+          message: error.message || "Internal Server Error",
+          code,
+          details: (error as any).details || (error as any).errors,
+          stack: isDev ? error.stack : undefined,
+        },
+      });
+    });
+  }
+
+  useGlobal(middleware: XMiddleware): void {
+    this.globalMiddlewares.push(middleware);
+  }
+
+  getGlobalMiddlewares(): readonly XMiddleware[] {
+    return [...this.globalMiddlewares];
+  }
+
+  /**
+   * Scan `apiDir` for `*.api.ts` modules and register routes on this Fastify instance.
+   */
+  async mountApi(apiDir: string, app: XApp): Promise<void> {
+    await mountApiRoutes(this.fastify, apiDir, app);
+  }
+
+  async listen(port: number): Promise<void> {
+    await this.fastify.listen({ port, host: "0.0.0.0" });
+    console.log(`\n  XAOCS running at http://localhost:${port}\n`);
+
+    if (!shutdownRegistered && process.env["APP_ENV"] !== "test") {
+      shutdownRegistered = true;
+      const gracefulShutdown = async (signal: string) => {
+        log.info(`Received ${signal} — shutting down gracefully...`);
+        try {
+          await this.close();
+          await closeDb();
+          process.exit(0);
+        } catch (err) {
+          log.error(`Error during graceful shutdown: ${(err as Error).message}`);
+          process.exit(1);
+        }
+      };
+
+      process.on("SIGTERM", () => void gracefulShutdown("SIGTERM"));
+      process.on("SIGINT", () => void gracefulShutdown("SIGINT"));
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.fastify.close();
+  }
+}
+

package/src/adapters/RequestAdapter.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "bun:test";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { adaptRequest, adaptResponse } from "./RequestAdapter";
+
+describe("RequestAdapter", () => {
+  it("adapts request shape", () => {
+    const req = {
+      params: { id: "42" },
+      query: { q: "ok" },
+      body: { x: 1 },
+      headers: { "x-test": "1" },
+    } as unknown as FastifyRequest;
+
+    const app = {
+      make: <T>(_key: string) => ({}) as T,
+    };
+
+    const adapted = adaptRequest(req, app);
+
+    expect(adapted.params["id"]).toBe("42");
+    expect(adapted.query["q"]).toBe("ok");
+  });
+
+  it("adapts response shape", () => {
+    let statusCode = 200;
+    let payload: unknown;
+
+    const reply = {
+      code(code: number) {
+        statusCode = code;
+        return this;
+      },
+      send(data: unknown) {
+        payload = data;
+        return this;
+      },
+      redirect(_url: string) {},
+    } as unknown as FastifyReply;
+
+    const adapted = adaptResponse(reply);
+
+    adapted.status(201).json({ ok: true });
+
+    expect(statusCode).toBe(201);
+    expect((adapted as any)._payload).toEqual({ ok: true });
+  });
+});
+

package/src/adapters/RequestAdapter.ts

@@ -0,0 +1,108 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { CookieOptions, XApp, XRequest, XResponse } from "@xacos/shared";
+import "@fastify/multipart";
+import { z } from 'zod';
+
+export function adaptRequest(req: FastifyRequest, app: XApp): XRequest {
+  const xReq: XRequest = {
+    ip: req.ip,
+    params: (req.params as Record<string, string>) ?? {},
+    query: (req.query as Record<string, string>) ?? {},
+    body: req.body,
+    headers: req.headers as Record<string, string | string[] | undefined>,
+    cookies: ((req as any).cookies as Record<string, string> | undefined) ?? {},
+    app,
+    validate(schema) {
+      const result = schema.safeParse(this.body);
+      if (!result.success) {
+        const error: any = new Error('Validation failed');
+        error.statusCode = 422;
+        error.code = 'VALIDATION_ERROR';
+        error.details = result.error.flatten().fieldErrors;
+        throw error;
+      }
+      return result.data;
+    },
+    async file(name: string) {
+      if (!(req as any).isMultipart()) return undefined;
+      
+      const fileIter = (req as any).files();
+      for await (const part of fileIter) {
+        if (part.fieldname === name) {
+          return createXFile(part, app);
+        }
+      }
+      return undefined;
+    },
+    async files(name?: string) {
+      if (!(req as any).isMultipart()) return [];
+
+      const results = [];
+      const fileIter = (req as any).files();
+      for await (const part of fileIter) {
+        if (!name || part.fieldname === name) {
+          results.push(createXFile(part, app));
+        }
+      }
+      return results;
+    }
+  };
+  return xReq;
+}
+
+function createXFile(part: any, app: XApp) {
+  return {
+    fieldname: part.fieldname,
+    filename: part.filename,
+    mimetype: part.mimetype,
+    encoding: part.encoding,
+    async getBuffer() {
+      return await part.toBuffer();
+    },
+    async store(path: string) {
+      const buf = await part.toBuffer();
+      const storage = app.make<any>('storage');
+      await storage.put(path, buf);
+      return path;
+    }
+  };
+}
+
+
+
+
+export function adaptResponse(reply: FastifyReply): XResponse {
+  const res: any = {
+    _payload: undefined,
+    setHeader(name: string, value: string) {
+      reply.header(name, value);
+      return res;
+    },
+    json(data: unknown) {
+      this._payload = data;
+      return res;
+    },
+    status(code: number) {
+      reply.code(code);
+      return res;
+    },
+    send(data?: string) {
+      this._payload = data ?? "";
+      return res;
+    },
+    redirect(url: string) {
+      reply.redirect(url);
+    },
+    setCookie(name: string, value: string, opts?: CookieOptions) {
+      const cookieReply = reply as FastifyReply & {
+        setCookie?: (cookieName: string, cookieValue: string, cookieOpts?: CookieOptions) => void;
+      };
+
+      cookieReply.setCookie?.(name, value, opts);
+      return res;
+    },
+  };
+
+  return res;
+}
+

package/src/dev/mountVite.ts

@@ -0,0 +1,90 @@
+import type { FastifyInstance } from 'fastify';
+import { createViteConfig, ViewScanner } from '@xacos/compiler';
+
+import { createServer as createViteServer, type InlineConfig } from 'vite';
+
+export async function mountViteDev(
+  fastify: FastifyInstance,
+  viewsDir: string,
+  root: string
+): Promise<void> {
+  const scanner = new ViewScanner(viewsDir);
+  const routes = scanner.scan();
+
+  // Register routes in Fastify so it knows about them, 
+  // even though Vite middleware will actually serve them.
+  for (const route of routes) {
+    fastify.get(route.path, async (request, reply) => {
+      const mod = await vite.ssrLoadModule(route.filePath);
+      
+      if (mod['ssr'] === true) {
+        const Component = mod.default;
+        if (typeof Component !== 'function') {
+           throw new Error(`[XAOCS] Page at ${route.filePath} does not have a default export component`);
+        }
+        
+        // In dev mode, we still let Vite handle the HTML shell usually, 
+        // but for a true SSR opt-in, we might want to render the component here.
+        // For now, following the sprint goal: render to string if ssr=true.
+        const { renderSSR } = await import('@xacos/compiler');
+        const { html, meta } = await renderSSR(route.filePath, {
+          params: request.params as Record<string, string>,
+          query: request.query as Record<string, string>,
+        });
+
+        // We need a basic HTML shell. For now, we'll return the rendered HTML.
+        // Real implementation would inject into a template.
+        reply.type('text/html').send(`
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <title>${meta.title ?? 'XAOCS App'}</title>
+              ${meta.description ? `<meta name="description" content="${meta.description}">` : ''}
+            </head>
+            <body>
+              <div id="root">${html}</div>
+            </body>
+          </html>
+        `);
+        return;
+      }
+
+      // The onRequest hook handles the actual Vite forwarding for non-SSR.
+      return reply.callNotFound(); 
+    });
+  }
+
+
+  const config = createViteConfig(viewsDir, root) as unknown as InlineConfig;
+  const vite = await createViteServer(config);
+
+
+
+  // Forward all non-API requests to Vite in dev mode
+  fastify.addHook('onRequest', async (request, reply) => {
+    const url = request.raw.url ?? '/';
+    // Skip API routes — those are handled by XAOCS API router
+    if (url.startsWith('/api/')) return;
+
+    // Use Vite's connect-style middleware
+    return new Promise<void>((resolve, reject) => {
+      vite.middlewares(request.raw, reply.raw, (err: unknown) => {
+
+        if (err) {
+          reject(err);
+        } else {
+          // If Vite doesn't handle it, it will call next()
+          // We don't really have a 'next' in Fastify onRequest hook in this way,
+          // but resolve() lets Fastify continue.
+          resolve();
+        }
+      });
+    });
+  });
+
+  // Handle graceful shutdown
+  fastify.addHook('onClose', async () => {
+    await vite.close();
+  });
+}
+

package/src/index.ts

@@ -0,0 +1,9 @@
+export { XServer } from "./XServer";
+export { adaptRequest, adaptResponse } from "./adapters/RequestAdapter";
+export { mountApiRoutes } from "./routing/mountApiRoutes";
+export { mountViteDev } from "./dev/mountVite";
+export { mountViewRoutes } from "./views/mountViewRoutes";
+export { serveStaticChunks } from "./static/serveStaticChunks";
+export { buildHtmlShell, type HtmlShellOptions } from "./views/buildHtmlShell";
+export { Logger, log } from "./Logger";
+

package/src/routing/mountApiRoutes.ts

@@ -0,0 +1,152 @@
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+import type { FastifyInstance } from "fastify";
+import type { XApp } from "@xacos/shared";
+import { scanApiFiles, compose, invalidateScanCache } from "@xacos/core";
+import { adaptRequest, adaptResponse } from "../adapters/RequestAdapter";
+import { validate, ValidationError } from "@xacos/validation";
+import { log } from "../Logger";
+
+interface ActiveRouteMeta {
+  route: any;
+  pipeline: any;
+}
+
+// WeakMap scoping route registries per Fastify instance
+const serverRoutesRegistry = new WeakMap<FastifyInstance, Map<string, ActiveRouteMeta>>();
+// Track if chokidar watcher is already initialized for this fastify instance
+const activeWatchers = new WeakSet<FastifyInstance>();
+
+export async function mountApiRoutes(
+  fastify: FastifyInstance,
+  apiDir: string,
+  app: XApp,
+): Promise<void> {
+  let activeRoutesRegistry = serverRoutesRegistry.get(fastify);
+  if (!activeRoutesRegistry) {
+    activeRoutesRegistry = new Map<string, ActiveRouteMeta>();
+    serverRoutesRegistry.set(fastify, activeRoutesRegistry);
+  }
+
+  invalidateScanCache();
+  const files = scanApiFiles(apiDir);
+
+  for (const { filePath, urlPrefix } of files) {
+    try {
+      const mod = await import(pathToFileURL(filePath).href);
+      const router = mod?.router;
+      if (!router) continue;
+
+      for (const route of router.routes) {
+        const routePath = route.path === "/" ? "" : route.path;
+        const fullPath = `${urlPrefix}${routePath}`.replace(/\/+/g, "/");
+        const pipeline = route.middlewares && route.middlewares.length ? compose(route.middlewares) : null;
+        const routeKey = `${route.method}:${fullPath}`;
+
+        if (activeRoutesRegistry.has(routeKey)) {
+          activeRoutesRegistry.set(routeKey, { route, pipeline });
+        } else {
+          activeRoutesRegistry.set(routeKey, { route, pipeline });
+
+          fastify.route({
+            method: route.method,
+            url: fullPath,
+            handler: async (request, reply) => {
+              // Ensure we retrieve from the instance-scoped registry at request time
+              const registry = serverRoutesRegistry.get(fastify);
+              const meta = registry?.get(routeKey);
+              if (!meta) {
+                void reply.code(404);
+                return { error: "Route not found" };
+              }
+              const currentRoute = meta.route;
+              const currentPipeline = meta.pipeline;
+
+              const req = adaptRequest(request, app);
+              const res = adaptResponse(reply);
+
+              try {
+                if (currentRoute.schema) {
+                  if (currentRoute.schema.body) validate(req.body, currentRoute.schema.body);
+                  if (currentRoute.schema.query) validate(req.query as unknown, currentRoute.schema.query);
+                  if (currentRoute.schema.params) validate(req.params as unknown, currentRoute.schema.params);
+                }
+
+                if (currentPipeline) {
+                  await currentPipeline(req, res);
+                }
+
+                await currentRoute.handler(req, res);
+                if ((res as unknown as { _payload?: unknown })._payload !== undefined) {
+                  return (res as unknown as { _payload: unknown })._payload;
+                }
+              } catch (e) {
+                if (e instanceof ValidationError) {
+                  void reply.code(e.statusCode);
+                  return { errors: e.errors };
+                }
+                throw e;
+              }
+            },
+          });
+        }
+      }
+    } catch (err) {
+      console.error("IMPORT ERROR:", err);
+      log.error(`Failed to mount API file ${filePath}: ${(err as Error).message}`);
+    }
+  }
+
+  if (process.env["APP_ENV"] !== "production" && !activeWatchers.has(fastify)) {
+    activeWatchers.add(fastify);
+    try {
+      const chokidar = await import("chokidar");
+      const watcher = chokidar.watch([apiDir, resolve(apiDir, "../app")], {
+        ignoreInitial: true,
+      });
+
+      fastify.addHook("onClose", async () => {
+        await watcher.close();
+        activeWatchers.delete(fastify);
+      });
+
+      watcher.on("all", (event, path) => {
+        log.info(`[HMR] Detected change in ${path} (${event})`);
+        void (async () => {
+          try {
+            const registry = serverRoutesRegistry.get(fastify);
+            if (!registry) return;
+
+            invalidateScanCache();
+            const updatedFiles = scanApiFiles(apiDir);
+            for (const { filePath, urlPrefix } of updatedFiles) {
+              const mod = await import(pathToFileURL(filePath).href + "?t=" + Date.now());
+              const router = mod?.router;
+              if (!router) continue;
+
+              for (const route of router.routes) {
+                const routePath = route.path === "/" ? "" : route.path;
+                const fullPath = `${urlPrefix}${routePath}`.replace(/\/+/g, "/");
+                const pipeline = route.middlewares && route.middlewares.length ? compose(route.middlewares) : null;
+                const routeKey = `${route.method}:${fullPath}`;
+
+                if (registry.has(routeKey)) {
+                  registry.set(routeKey, { route, pipeline });
+                  log.info(`[HMR] Hot-swapped route ${route.method} ${fullPath}`);
+                } else {
+                  registry.set(routeKey, { route, pipeline });
+                  log.info(`[HMR] Registered new route ${route.method} ${fullPath}`);
+                }
+              }
+            }
+          } catch (err) {
+            log.error(`[HMR] Failed to hot-reload routes: ${(err as Error).message}`);
+          }
+        })();
+      });
+    } catch (err) {
+      log.error(`[HMR] Failed to initialize chokidar: ${(err as Error).message}`);
+    }
+  }
+}
+

package/src/static/serveStaticChunks.ts

@@ -0,0 +1,21 @@
+import type { FastifyInstance } from 'fastify';
+import { resolve } from 'path';
+
+/**
+ * Serves production view bundles generated by esbuild.
+ * Chunks are served under the /__xacos/ prefix.
+ */
+export async function serveStaticChunks(
+  fastify: FastifyInstance,
+  chunksDir: string
+): Promise<void> {
+  // @ts-ignore - Dynamic import of @fastify/static
+  const fastifyStatic = (await import('@fastify/static')).default;
+
+  await fastify.register(fastifyStatic, {
+    root: resolve(chunksDir),
+    prefix: '/__xacos/',
+    decorateReply: false, // Avoid collision if already registered
+  });
+}
+

package/src/views/buildHtmlShell.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'bun:test';
+import { buildHtmlShell } from './buildHtmlShell';
+
+describe('buildHtmlShell', () => {
+  it('injects chunk URL and meta tags', () => {
+    const html = buildHtmlShell({
+      chunkUrl: '/__xacos/home.js',
+      meta: { title: 'Home', description: 'Testing' }
+    });
+    
+    expect(html).toContain('<title>Home</title>');
+    expect(html).toContain('description" content="Testing"');
+    expect(html).toContain('src="/__xacos/home.js"');
+    expect(html).toContain('<div id="root"></div>');
+  });
+
+  it('injects SSR HTML into root div', () => {
+    const html = buildHtmlShell({
+      chunkUrl: '/__xacos/home.js',
+      ssrHtml: '<h1>SSR Content</h1>'
+    });
+    
+    expect(html).toContain('<div id="root"><h1>SSR Content</h1></div>');
+  });
+});
+

package/src/views/buildHtmlShell.ts

@@ -0,0 +1,35 @@
+export interface HtmlShellOptions {
+  chunkUrl: string;     // e.g. /__xacos/index.js
+  ssrHtml?: string;     // pre-rendered HTML (SSR only)
+  meta?: {
+    title?: string | undefined;
+    description?: string | undefined;
+  };
+}
+
+/**
+ * Generate a complete HTML shell for a page.
+ * Wires the page-specific JS chunk into the <script> tag.
+ */
+export function buildHtmlShell(options: HtmlShellOptions): string {
+  const { chunkUrl, ssrHtml = '', meta = {} } = options;
+
+  const headTags = [
+    `<title>${meta.title ?? 'XAOCS App'}</title>`,
+    meta.description ? `<meta name="description" content="${meta.description}" />` : '',
+    `<script type="module" src="${chunkUrl}"></script>`,
+  ].filter(Boolean).join('\n    ');
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  ${headTags}
+</head>
+<body>
+  <div id="root">${ssrHtml}</div>
+</body>
+</html>`;
+}
+