slicejs-web-framework 4.0.1 → 4.1.0

package/api/framework/server.js

@@ -11,11 +11,327 @@ import {
 import { createPublicEnvProvider } from './publicEnvResolver.js';
 import { createDevDepsOptimizer } from './devDepsOptimizer.js';
 import { createPrecompressedStatic } from './precompressedStatic.js';
-
-export function createSliceServer(options = {}) {
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import zlib from 'node:zlib';
+import {
+  injectHead,
+  loadSeoManifest,
+  matchPathPattern,
+  normalizeOrigin,
+  pickRouteEntry,
+  renderHead,
+  resolveMetadata,
+  routePaths
+} from './seo.js';
+
+// ── Shared runtime context ─────────────────────────────────────────
+// `createSliceServer` and the standalone `sliceFallback` must agree on where the
+// app lives and which folder it serves, without one having to call the other.
+
+function resolveRuntimeContext(options = {}) {
   const projectRoot = options.projectRoot || process.cwd();
-  const runMode = process.env.NODE_ENV === 'production' ? 'production' : 'development';
+  const runMode = options.mode || (process.env.NODE_ENV === 'production' ? 'production' : 'development');
   const folderDeployed = runMode === 'production' ? 'dist' : 'src';
+  return { projectRoot, runMode, folderDeployed };
+}
+
+/** Component URL prefixes, from sliceConfig. Used by the development carve-outs. */
+function readComponentPrefixes(projectRoot) {
+  for (const folder of ['src', 'dist']) {
+    const file = path.join(projectRoot, folder, 'sliceConfig.json');
+    if (!fs.existsSync(file)) continue;
+    try {
+      const config = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return Object.values(config.paths?.components || {})
+        .map((entry) => entry?.path)
+        .filter(Boolean);
+    } catch {
+      // unreadable config: fall through to "no prefixes" (no carve-out, as before)
+    }
+  }
+  return [];
+}
+
+/**
+ * True for `/Components/<Category>/<Name>/<Name>.css` when the component's `.js`
+ * exists but it has no stylesheet. JS-only Visual components (MultiRoute,
+ * DemoButton…) legitimately ship no CSS, and a 404 there makes `slice.build`
+ * return null in development.
+ */
+function isComponentWithoutStylesheet(pathname, projectRoot, folderDeployed, prefixes) {
+  if (!pathname.endsWith('.css') || pathname.includes('..')) return false;
+  if (!prefixes.some((prefix) => pathname.startsWith(`${prefix}/`))) return false;
+  const file = path.join(projectRoot, folderDeployed, pathname);
+  return !fs.existsSync(file) && fs.existsSync(file.replace(/\.css$/, '.js'));
+}
+
+/**
+ * The terminal middleware: everything the app did not answer lands here.
+ *
+ * Mounted by `start()` — and exported so an app that never calls `start()` (a
+ * serverless adapter, a supertest harness) can close the chain by hand. It must
+ * be the last middleware; mounting it twice is harmless (the first one ends the
+ * response) but pointless, and `start()` skips it when it is already there.
+ *
+ * `options.seo` is the **prepared** context from `prepareSeo()`, not the config.
+ */
+export function sliceFallback(options = {}) {
+  const { projectRoot, runMode, folderDeployed } = resolveRuntimeContext(options);
+  const isDev = runMode === 'development';
+  const shellPath = path.join(projectRoot, folderDeployed, 'App', 'index.html');
+  const prefixes = options.componentPrefixes || readComponentPrefixes(projectRoot);
+  const seo = options.seo?.resolve ? options.seo : null;
+
+  const sendShell = (req, res) => {
+    res.setHeader('Cache-Control', 'no-cache');
+    res.sendFile(shellPath, (error) => {
+      if (!error) return;
+      if (res.headersSent) return;
+      console.error(`[SPA Fallback] Error sending ${shellPath}:`, error);
+      res.status(500).send('<h1>500 - Internal Server Error</h1><p>Could not serve application file</p>');
+    });
+  };
+
+  /** Precomputed HTML, or the shell: same encoding dance either way. */
+  const sendRendered = (req, res, page, status) => {
+    res.status(status);
+    res.setHeader('Cache-Control', status === 200 ? 'no-cache' : 'no-store');
+    if (page.etag) {
+      res.setHeader('ETag', page.etag);
+      if (req.headers['if-none-match'] === page.etag) return res.status(304).end();
+    }
+
+    const accept = String(req.headers['accept-encoding'] || '');
+    let body = page.html;
+    if (page.br && /\bbr\b/.test(accept)) {
+      res.setHeader('Content-Encoding', 'br');
+      body = page.br;
+    } else if (page.gzip && /\bgzip\b/.test(accept)) {
+      res.setHeader('Content-Encoding', 'gzip');
+      body = page.gzip;
+    }
+
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    res.setHeader('Vary', 'Accept-Encoding');
+    res.setHeader('Content-Length', String(body.length));
+    return res.end(body);
+  };
+
+  const fallback = (req, res, next) => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return next();
+
+    const pathname = decodeURI(req.path).replace(/\/+$/, '') || '/';
+
+    // Unknown /api paths answer JSON, never the shell. This used to live in the
+    // factory, where it swallowed every API router the app mounted afterwards.
+    if (pathname === '/api' || pathname.startsWith('/api/')) {
+      return res.status(404).json({ error: 'API route not found', path: req.originalUrl });
+    }
+
+    if (isDev) {
+      // Development serves components unbundled: the framework fetches
+      // `<Component>.html` and `.css` over HTTP, and a JS-only component has
+      // neither. A 404 here makes `slice.build` return null and the page dies.
+      if (pathname.endsWith('.html')) return sendShell(req, res);
+      if (isComponentWithoutStylesheet(pathname, projectRoot, folderDeployed, prefixes)) {
+        res.status(200);
+        res.setHeader('Content-Type', 'text/css; charset=utf-8');
+        res.setHeader('Cache-Control', 'no-store');
+        return res.end('/* component ships no stylesheet */');
+      }
+    }
+
+    // With SEO configured the route set is known, so this is also where the
+    // 200-vs-404 decision happens.
+    if (seo) {
+      const { status, page } = seo.resolve(pathname);
+      return sendRendered(req, res, page, status);
+    }
+
+    return sendShell(req, res);
+  };
+
+  fallback.__sliceFallback = true;
+  return fallback;
+}
+
+const encodeSeoPage = (html) => {
+  const raw = Buffer.from(html, 'utf8');
+  return {
+    html: raw,
+    gzip: zlib.gzipSync(raw, { level: 9 }),
+    br: zlib.brotliCompressSync(raw, {
+      params: { [zlib.constants.BROTLI_PARAM_QUALITY]: 9 }
+    }),
+    etag: `W/"${createHash('sha1').update(raw).digest('base64url')}"`
+  };
+};
+
+/**
+ * Resolve a manifest (or image manifest) path. A relative path is tried at the
+ * project root first (small apps keep `seo.json` there), then inside the
+ * deployed `public/` folder, which is where generated artifacts live.
+ */
+function resolveSeoFile(projectRoot, folderDeployed, file) {
+  const candidates = [
+    path.resolve(projectRoot, file),
+    path.join(projectRoot, folderDeployed, 'public', file),
+    path.join(projectRoot, folderDeployed, file)
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
+}
+
+async function loadRouteDefinitions(projectRoot, folderDeployed) {
+  const candidates = [
+    path.join(projectRoot, folderDeployed, 'routes.js'),
+    path.join(projectRoot, 'src', 'routes.js')
+  ];
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) continue;
+    const module = await import(pathToFileURL(candidate).href);
+    const routes = module.default ?? module.routes ?? [];
+    return (Array.isArray(routes) ? routes : []).map((route) => ({
+      path: String(route?.path ?? '').replace(/\/+$/, '') || '/',
+      metadata: route?.metadata || {}
+    })).filter((route) => route.path);
+  }
+  return [];
+}
+
+/**
+ * Reads the manifest and `routes.js`, renders every literal route once and
+ * returns the resolver `sliceFallback` uses. Async because `routes.js` is an
+ * ESM import — `start()` awaits it, so the first request never pays for it.
+ *
+ * `config` is the `seo` block from `createSliceServer({ seo })`: a JSON path (or
+ * an already-loaded object) plus an optional origin override.
+ */
+export async function prepareSeo(options = {}) {
+  const { projectRoot, runMode, folderDeployed } = resolveRuntimeContext(options);
+  const config = options.seo || {};
+  if (!config || (typeof config === 'object' && !config.manifest && !config.routes)) return null;
+
+  const manifest = typeof config.manifest === 'object'
+    ? config.manifest
+    : loadSeoManifest(resolveSeoFile(projectRoot, folderDeployed, config.manifest || 'seo.json'));
+  if (!manifest) return null;
+
+  // Social cards are generated after the manifest (they need a browser), so the
+  // app points at that file instead of inlining 70 image paths. An entry that
+  // declares its own image always wins.
+  const imageManifest = typeof config.images === 'object'
+    ? config.images
+    : config.images
+      ? loadSeoManifest(resolveSeoFile(projectRoot, folderDeployed, config.images))
+      : null;
+  const cards = imageManifest?.images || {};
+
+  const port = options.port || process.env.PORT || 3001;
+  const origin = normalizeOrigin(config.origin)
+    || normalizeOrigin(process.env.SLICE_ORIGIN)
+    || normalizeOrigin(manifest.origin)
+    || (runMode === 'development' ? `http://localhost:${port}` : null);
+
+  if (!origin) {
+    throw new Error(
+      'seo: an absolute origin is required in production. Set seo.origin, SLICE_ORIGIN or seo.json origin.'
+    );
+  }
+
+  const shellPath = path.join(projectRoot, folderDeployed, 'App', 'index.html');
+  const shell = fs.readFileSync(shellPath, 'utf8');
+  const siteName = config.siteName || manifest.defaults?.siteName || null;
+  const locale = config.locale || manifest.defaults?.locale || null;
+  const routes = await loadRouteDefinitions(projectRoot, folderDeployed);
+
+  const render = (pathname, routeMetadata) => {
+    const meta = resolveMetadata({ pathname, routeMetadata, manifest, origin });
+
+    // Precedence: an image declared on the route entry wins, then the generated
+    // card, then `defaults.image` (the generic banner). Comparing against the raw
+    // entry keeps the framework from guessing where the image came from.
+    const explicitImage = pickRouteEntry(pathname, manifest)?.entry?.image;
+    const card = cards[pathname];
+    if (card && !explicitImage && !routeMetadata?.image) {
+      meta.image = /^https?:\/\//i.test(card.path) ? card.path : `${origin}${card.path}`;
+      meta.imageWidth = card.width ?? null;
+      meta.imageHeight = card.height ?? null;
+      meta.imageType = card.type || null;
+      meta.imageAlt = meta.imageAlt || meta.title;
+    }
+
+    return encodeSeoPage(injectHead(shell, renderHead(meta, { siteName, locale })));
+  };
+
+  const pages = new Map();
+  const patterns = [];
+  for (const route of routes) {
+    if (/\$\{[^}]+\}/.test(route.path)) {
+      patterns.push(route);
+      continue;
+    }
+    pages.set(route.path, render(route.path, route.metadata));
+  }
+  // Longest pattern first so `/p/${id}/detail` wins over `/p/${id}`.
+  patterns.sort((a, b) => b.path.length - a.path.length);
+
+  const notFound = encodeSeoPage(injectHead(
+    shell,
+    '<title>Not found</title>\n    <meta name="robots" content="noindex, nofollow" />'
+  ));
+
+  // A `${param}` route cannot be enumerated, so it is rendered per path. The
+  // cache keeps repeated visits of the same product from recompressing.
+  const dynamicPages = new Map();
+  const DYNAMIC_LIMIT = 200;
+
+  return {
+    origin,
+    manifest,
+    routes,
+    prerendered: pages.size,
+    resolve(pathname) {
+      const exact = pages.get(pathname);
+      if (exact) return { status: 200, page: exact };
+
+      const dynamic = dynamicPages.get(pathname);
+      if (dynamic) return { status: 200, page: dynamic };
+
+      for (const route of patterns) {
+        if (!matchPathPattern(route.path, pathname)) continue;
+        const page = render(pathname, route.metadata);
+        if (dynamicPages.size >= DYNAMIC_LIMIT) {
+          dynamicPages.delete(dynamicPages.keys().next().value);
+        }
+        dynamicPages.set(pathname, page);
+        return { status: 200, page };
+      }
+
+      return { status: 404, page: notFound };
+    }
+  };
+}
+
+/**
+ * The error handler that has to sit after the fallback (Express only routes an
+ * error to middleware registered later in the stack). Exported for the same
+ * no-`start()` case as `sliceFallback`.
+ */
+export function sliceErrorHandler(options = {}) {
+  const { runMode } = resolveRuntimeContext(options);
+  return (error, req, res, next) => {
+    console.error('[Server Error]', error.stack || error.message || error);
+    if (res.headersSent) return next(error);
+    res.status(error.status || 500).json({
+      error: 'Internal Server Error',
+      message: runMode === 'production' ? 'An unexpected error occurred' : error.message
+    });
+  };
+}
+
+export function createSliceServer(options = {}) {
+  const { projectRoot, runMode, folderDeployed } = resolveRuntimeContext(options);
 
   let sliceConfig = {};
   try {
@@ -35,7 +351,7 @@ export function createSliceServer(options = {}) {
     frameworkVersion = 'unknown';
   }
 
-  const PORT = process.env.PORT || sliceConfig.server?.port || 3001;
+  const PORT = options.port ?? process.env.PORT ?? sliceConfig.server?.port ?? 3001;
 
   const publicEnvProvider = createPublicEnvProvider({
     mode: runMode,
@@ -175,28 +491,53 @@ export function createSliceServer(options = {}) {
     app.use('/Components', (req, res) => res.status(404).send('Not found'));
   }
 
+  // Bundles are unversioned build output: never cache them. Set before every
+  // handler that can answer a bundle (precompressed, the .js handler, static
+  // files and the /dist mirror) so the policy cannot depend on which one wins.
+  const noStoreBundlePaths = ['/bundles/', '/dist/bundles/'];
+  app.use(noStoreBundlePaths, (req, res, next) => {
+    res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+    res.setHeader('Pragma', 'no-cache');
+    res.setHeader('Expires', '0');
+    next();
+  });
+
   // Serve precompressed .br/.gz siblings (from `slice build --compress`) when the
   // client accepts them. Mounted before the bundle handler and static serves so
   // it wins, and its Content-Encoding makes the runtime `compression` middleware
   // skip re-compressing. Production only (dist holds the precompressed files).
   if (runMode === 'production') {
     const distRoot = path.join(projectRoot, folderDeployed);
-    app.use(createPrecompressedStatic([path.join(distRoot, 'public'), distRoot]));
+    app.use(createPrecompressedStatic([path.join(distRoot, 'public'), distRoot], {
+      noStorePrefixes: noStoreBundlePaths
+    }));
   }
 
   // Middleware personalizado para archivos de bundles con MIME types correctos
   app.use('/bundles/', (req, res, next) => {
-    if (req.path.endsWith('.js')) {
-      const filePath = path.join(projectRoot, folderDeployed, 'bundles', req.path);
+    if (req.path.endsWith('.js') || req.path.endsWith('.mjs')) {
+      const cleanedPath = req.path.replace(/^\//, '');
+      let filePath = path.join(projectRoot, folderDeployed, 'bundles', cleanedPath);
+
+      // Bundler v2 emits this import relative to /bundles even when the source
+      // file lives under Components/AppComponents/ComponentsPage. Without this,
+      // a production build 404s on a module it imported itself.
+      if (cleanedPath === 'documentationRoutes.generated.js' || cleanedPath === 'docsIndex.js') {
+        filePath = path.join(
+          projectRoot,
+          folderDeployed,
+          'Components',
+          'AppComponents',
+          'ComponentsPage',
+          cleanedPath
+        );
+      }
       console.log(`📂 Processing bundle: ${req.path} -> ${filePath}`);
 
       if (fs.existsSync(filePath)) {
         try {
           const fileContent = fs.readFileSync(filePath, 'utf8');
           res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
-          res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
-          res.setHeader('Pragma', 'no-cache');
-          res.setHeader('Expires', '0');
           console.log(`✅ Serving bundle: ${req.path} (${fileContent.length} bytes, ${Buffer.byteLength(fileContent, 'utf8')} bytes UTF-8)`);
           return res.send(fileContent);
         } catch (error) {
@@ -338,74 +679,100 @@ export function createSliceServer(options = {}) {
   // SEO: robots.txt & sitemap.xml
   // ==============================================
 
-  app.get('/robots.txt', (req, res) => {
-    res.sendFile(resolveDeployedFile('robots.txt'));
-  });
-
-  app.get('/sitemap.xml', (req, res) => {
-    res.sendFile(resolveDeployedFile('sitemap.xml'));
-  });
-
-  // ==============================================
-  // API 404 — las rutas /api/* irreconocibles devuelven JSON, no HTML
-  // ==============================================
+  // `sendFile` on a missing artifact routes to the error handler and answers
+  // 500; the files are optional, so a missing one is a 404.
+  const sendDeployedFile = (res, fileName) => {
+    const file = resolveDeployedFile(fileName);
+    if (!fs.existsSync(file)) return res.status(404).send(`${fileName} not found`);
+    return res.sendFile(file);
+  };
 
-  app.use('/api', (req, res) => {
-    res.status(404).json({ error: 'API route not found', path: req.originalUrl });
-  });
+  app.get('/robots.txt', (req, res) => sendDeployedFile(res, 'robots.txt'));
+  app.get('/sitemap.xml', (req, res) => sendDeployedFile(res, 'sitemap.xml'));
 
   // ==============================================
-  // SPA FALLBACK
+  // FIN DEL STACK — el fallback y el error handler los monta start()
   // ==============================================
-
-  app.get('*', (req, res) => {
-    const indexPath = path.join(projectRoot, folderDeployed, 'App', 'index.html');
-    res.sendFile(indexPath, (err) => {
-      if (err) {
-        console.error(`[SPA Fallback] Error sending ${indexPath}:`, err);
-        res.status(500).send(`<h1>500 - Internal Server Error</h1><p>Could not serve application file</p>`);
+  // Nothing terminal is registered here on purpose: a catch-all placed inside
+  // the factory makes every `app.use()` the app adds afterwards dead code.
+  // `sliceFallback()` owns "nobody answered" (shell, dev carve-outs, /api 404).
+
+  let started = false;
+
+  const hasFallbackMounted = () => {
+    // Express 4 exposes `app._router`; Express 5 exposes `app.router` (and keeps
+    // `_router`). On 4 the public getter throws when accessed, so both are read
+    // defensively: worst case the answer is "not mounted" and the fallback is
+    // added once more, which is harmless (the first one ends the response).
+    let stack;
+    try {
+      stack = app._router?.stack || [];
+    } catch {
+      stack = [];
+    }
+    if (!stack.length) {
+      try {
+        stack = app.router?.stack || [];
+      } catch {
+        stack = [];
       }
-    });
-  });
-
-  // ==============================================
-  // ERROR HANDLER CENTRALIZADO
-  // ==============================================
+    }
+    return stack.some((layer) => layer?.handle?.__sliceFallback === true);
+  };
 
-  app.use((err, req, res, next) => {
-    console.error('[Server Error]', err.stack || err.message || err);
-    if (res.headersSent) return next(err);
-    res.status(err.status || 500).json({
-      error: 'Internal Server Error',
-      message: process.env.NODE_ENV === 'production' ? 'An unexpected error occurred' : err.message
-    });
-  });
+  /**
+   * Finishes the app and starts listening. Async because the SEO context is
+   * prepared (manifest read, `routes.js` imported, every literal route
+   * prerendered) before the first request can arrive.
+   * @param {{ port?: number, host?: string, signals?: boolean }} [startOptions]
+   * @returns {Promise<import('http').Server>}
+   */
+  async function start(startOptions = {}) {
+    if (started) throw new Error('Slice server: start() was already called');
+    started = true;
+
+    const { port = PORT, host, signals = true } = startOptions;
+
+    let seo = null;
+    if (options.seo) {
+      seo = await prepareSeo({ ...options, port });
+      if (seo) {
+        console.log(`🔎 SEO: ${seo.prerendered} routes prerendered (${seo.origin})`);
+      } else {
+        console.warn('[slice] seo options were given but no manifest was found; SEO is off.');
+      }
+    }
 
-  // ==============================================
-  // INICIO DEL SERVIDOR
-  // ==============================================
+    if (!hasFallbackMounted()) {
+      app.use(sliceFallback({ ...options, seo }));
+      app.use(sliceErrorHandler(options));
+    }
 
-  function startServer() {
-    const server = app.listen(PORT, () => {
-      console.log(`🔒 Security middleware: active (zero-config, automatic)`);
-      console.log(`🚀 Slice.js server running on port ${PORT}`);
-    });
+    if (port !== 0 && Number(port) !== Number(PORT)) {
+      console.warn(
+        `[slice] starting on port ${port}, but the security middleware was configured for ${PORT}. ` +
+        'Pass `port` to createSliceServer() as well, or set PORT, if the local app is refused.'
+      );
+    }
 
-    process.on('SIGINT', () => {
-      console.log('\n🛑 Slice server stopped');
-      process.exit(0);
+    const server = app.listen(port, host, () => {
+      console.log('🔒 Security middleware: active (zero-config, automatic)');
+      console.log(`🚀 Slice.js server running on port ${server.address()?.port ?? port}`);
     });
 
-    process.on('SIGTERM', () => {
-      console.log('\n🛑 Server terminated');
-      process.exit(0);
-    });
+    if (signals) {
+      const shutdown = (label) => () => {
+        console.log(label);
+        const force = setTimeout(() => process.exit(0), 5000);
+        force.unref?.();
+        server.close(() => process.exit(0));
+      };
+      process.once('SIGINT', shutdown('\n🛑 Slice server stopped'));
+      process.once('SIGTERM', shutdown('\n🛑 Server terminated'));
+    }
 
     return server;
   }
 
-  return {
-    app,
-    start: startServer
-  };
+  return { app, start };
 }

package/api/index.js

@@ -1,7 +1,17 @@
-// api/index.js - Punto de entrada del servidor
-import { createSliceServer } from 'slicejs-web-framework/api/framework/server.js';
-
-const server = createSliceServer();
-server.start();
-
-export default server.app;
+// api/index.js — server entrypoint.
+//
+// Everything you add goes between createSliceServer() and start(): ordinary
+// Express middleware, an /api router, auth, request logging. start() mounts the
+// terminal fallback (the only middleware that must be last), prepares SEO when
+// it is configured, and then listens.
+//
+//   const { app, start } = createSliceServer();
+//   app.use('/api/hooks', hooks);
+//   await start();
+import { createSliceServer } from 'slicejs-web-framework/api/framework/server.js';
+
+const { app, start } = createSliceServer();
+
+await start();
+
+export default app;