glashjs 0.0.3 → 0.1.0

package/README.md

@@ -49,6 +49,36 @@ Nothing is unhackable. glashjs ships strong, opinionated defaults so you're secu
 - **Subresource Integrity** helper (`sri()`) for build assets
 - Emitted to `glash-headers.json` for the edge, plus a `glashSecurity()` Express middleware
 
+## Routing, SSR & API (new in 0.1)
+glashjs now has a real server runtime — **file-based routing**, **server-side rendering**, and **API routes** — on Node built-ins, zero deps.
+
+```
+routes/
+  index.mjs          ->  /                 (SSR page)
+  about.mjs          ->  /about
+  blog/[slug].mjs    ->  /blog/:slug       (dynamic segment -> ctx.params.slug)
+  docs/[...path].mjs ->  /docs/*           (catch-all)
+  api/hello.mjs      ->  /api/hello        (API: export GET/POST/…)
+```
+
+```js
+// routes/index.mjs  — a server-rendered page (XSS-safe `html` template)
+import { html } from 'glashjs';
+export default (ctx) => ({ title: 'Home', body: html`<h1>Hello ${ctx.query.name}</h1>` });
+
+// routes/api/hello.mjs — an API route
+import { json } from 'glashjs';
+export const GET  = (ctx) => ({ ok: true, name: ctx.query.name });
+export const POST = (ctx) => json({ created: ctx.body }, { status: 201 });
+```
+
+```bash
+glash dev      # dev server: routing + SSR + API, live route reload
+glash serve    # production server over routes/ + built assets (Brotli-negotiated)
+```
+
+Every response carries the secure-by-default headers; static files are served from the build with Brotli negotiation. **Honest scope:** this is real SSR of HTML (render functions) — React/JSX components with client hydration, layouts/nested routing, client-JS bundling, and HMR are the next milestones (below).
+
 ## Usage
 
 ```js
@@ -92,10 +122,14 @@ animatedFavicon: true,                         // bundled animated glash mark (d
 - [x] Asset optimizer (Brotli/Gzip real; AVIF/WebP/AV1 via optional sharp/ffmpeg)
 - [x] Offline Service Worker + PWA manifest
 - [x] Secure-by-default headers + CSP + SRI
+- [x] File-based routing (pages + `api/`, dynamic `[param]` & catch-all `[...path]`)
+- [x] Server-side rendering (XSS-safe `html` templates) + full-document runtime
+- [x] API routes (per-method handlers, JSON body parsing, typed `json()` responses)
+- [x] Dev/prod server with live route reload + Brotli-negotiated static serving
+- [ ] React/JSX components + client hydration, nested layouts, streaming SSR
+- [ ] Client-JS bundling + HMR (on esbuild/Vite)
 - [ ] `<Image>` / `<Video>` components that emit `<picture>`/`<source>` from the manifest
-- [ ] Dev server + HMR (on Vite/esbuild) and file-based routing
-- [ ] SSR / streaming + edge adapter for the glashdb Worker (serve `.br`/`.avif` by `Accept`)
-- [ ] Signed, immutable asset URLs + automatic SRI injection into HTML
+- [ ] Edge adapter for the glashdb Worker (serve `.br`/`.avif` by `Accept`)
 - [ ] `glash deploy` → glashdb hosting in one command
 
 ## Design stance

package/bin/glash.mjs

@@ -3,6 +3,7 @@
 import { readFileSync } from 'node:fs';
 import { build } from '../src/build.mjs';
 import { optimizeAssets } from '../src/assets/optimize.mjs';
+import { createGlashServer } from '../src/server/server.mjs';
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const [, , cmd, ...rest] = process.argv;
@@ -12,12 +13,32 @@ function arg(name, fallback) {
   return i >= 0 && rest[i + 1] ? rest[i + 1] : fallback;
 }
 
+async function serve(dev) {
+  const root = arg('--root', process.cwd());
+  const { listen, cfg, routes } = await createGlashServer({ root, dev });
+  const port = Number(arg('--port', cfg.port || 3000));
+  const { host } = await listen(port);
+  const pages = routes.filter((r) => !r.isApi).length;
+  const apis = routes.filter((r) => r.isApi).length;
+  console.log(`\nglashjs ${dev ? 'dev' : 'serve'} — "${cfg.name}"`);
+  console.log(`  ${pages} page route(s), ${apis} api route(s)`);
+  routes.forEach((r) => console.log(`    ${r.isApi ? 'api ' : 'page'}  ${r.pattern}`));
+  console.log(`\n  ▶ http://localhost:${port}${dev ? '   (live route reload)' : ''}\n`);
+}
+
 async function main() {
   switch (cmd) {
     case 'build': {
       await build({ root: arg('--root', process.cwd()) });
       break;
     }
+    case 'dev':
+      await serve(true);
+      break;
+    case 'serve':
+    case 'start':
+      await serve(false);
+      break;
     case 'optimize': {
       const dir = rest[0] && !rest[0].startsWith('--') ? rest[0] : 'public';
       console.log(`glashjs optimize — ${dir}\n`);
@@ -35,6 +56,8 @@ async function main() {
       console.log(`glashjs — fast, offline-capable, hard-to-hack sites
 
 Usage:
+  glash dev [--port 3000]       Run the dev server (file-based routing, SSR, API, live reload)
+  glash serve [--port 3000]     Run the production server over routes/ + built assets
   glash build [--root <dir>]    Optimize assets, generate offline SW + PWA + security manifests
   glash optimize [<dir>]        Just run the asset optimizer over a directory
   glash version                 Print version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "glashjs",
-  "version": "0.0.3",
-  "description": "glashjs — a build pipeline + runtime conventions for fast, offline-capable, hard-to-hack sites. Built on proven primitives, with a best-in-class asset optimizer, PWA offline layer, and secure-by-default headers.",
+  "version": "0.1.0",
+  "description": "glashjs — a web framework with file-based routing, SSR, API routes, a best-in-class asset optimizer, offline PWA layer, animated favicon, and secure-by-default headers. Zero dependencies.",
   "type": "module",
   "bin": {
     "glash": "bin/glash.mjs"
@@ -37,7 +37,12 @@
     "asset-optimization",
     "avif",
     "brotli",
-    "security"
+    "security",
+    "routing",
+    "ssr",
+    "api",
+    "server",
+    "web-framework"
   ],
   "license": "MIT"
 }

package/src/config.mjs

@@ -17,6 +17,9 @@ export const DEFAULT_CONFIG = {
   // false disables it. Emits `glash-favicon.mjs` — call startGlashFavicon() once.
   animatedFavicon: true,
   publicDir: 'public',
+  // File-based routes (pages + api/) served by `glash dev` / `glash serve`.
+  routesDir: 'routes',
+  port: 3000,
   outDir: '.glash/out',
   themeColor: '#0b0d12',
   offline: true,

package/src/index.mjs

@@ -5,3 +5,6 @@ export { optimizeAssets } from './assets/optimize.mjs';
 export { generateAnimatedFavicon } from './assets/animated-favicon.mjs';
 export { generateServiceWorker } from './offline/generate-sw.mjs';
 export { securityHeaders, buildCsp, sri, glashSecurity } from './security/headers.mjs';
+export { createGlashServer, json } from './server/server.mjs';
+export { discoverRoutes, matchRoute } from './server/router.mjs';
+export { html, raw, escapeHtml, renderDocument } from './server/html.mjs';

package/src/server/html.mjs

@@ -0,0 +1,68 @@
+// glashjs SSR HTML layer
+// ---------------------------------------------------------------------------
+// A secure-by-default templating helper + full-document renderer. The `html`
+// tagged template ESCAPES every interpolation (so user data can't inject
+// markup — XSS-safe by default, matching the security pillar). Use `raw()` to
+// deliberately embed already-rendered HTML (e.g. a nested component).
+export function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (c) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[c]));
+}
+
+export function raw(value) {
+  return { __raw: String(value) };
+}
+
+function interpolate(v) {
+  if (v == null || v === false) return '';
+  if (Array.isArray(v)) return v.map(interpolate).join('');
+  if (typeof v === 'object' && '__raw' in v) return v.__raw;
+  return escapeHtml(v);
+}
+
+export function html(strings, ...values) {
+  let out = '';
+  strings.forEach((str, i) => { out += str + (i < values.length ? interpolate(values[i]) : ''); });
+  return raw(out);
+}
+
+/**
+ * Wrap a page body into a full HTML document with the glashjs runtime wired in:
+ * favicon, animated-favicon runtime, and offline service-worker registration.
+ * The runtime imports are resilient (try/catch) so pages still render in `dev`
+ * before a `glash build` has produced those files.
+ */
+export function renderDocument({
+  title = 'glashjs',
+  head = '',
+  body = '',
+  lang = 'en',
+  favicon = '/favicon.svg',
+  offline = true,
+  animatedFavicon = true,
+} = {}) {
+  const headHtml = typeof head === 'object' && head?.__raw ? head.__raw : String(head ?? '');
+  const bodyHtml = typeof body === 'object' && body?.__raw ? body.__raw : String(body ?? '');
+  const fav = animatedFavicon
+    ? '<script type="module">try{const m=await import("/glash-favicon.mjs");m.startGlashFavicon&&m.startGlashFavicon();}catch{}</script>'
+    : '';
+  const off = offline
+    ? '<script type="module">try{const m=await import("/glash-offline.mjs");m.registerGlashOffline&&m.registerGlashOffline();}catch{}</script>'
+    : '';
+  return `<!doctype html>
+<html lang="${escapeHtml(lang)}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<link rel="icon" href="${escapeHtml(favicon)}" type="image/svg+xml">
+<link rel="manifest" href="/manifest.webmanifest">
+${headHtml}
+</head>
+<body>
+${bodyHtml}
+${fav}${off}
+</body>
+</html>`;
+}

package/src/server/router.mjs

@@ -0,0 +1,76 @@
+// glashjs file-based router
+// ---------------------------------------------------------------------------
+// Maps files under the routes/ dir to URL patterns, Next-style:
+//   routes/index.mjs          -> /
+//   routes/about.mjs          -> /about
+//   routes/blog/[slug].mjs    -> /blog/:slug      (dynamic segment)
+//   routes/docs/[...path].mjs -> /docs/*path       (catch-all)
+//   routes/api/hello.mjs      -> /api/hello        (API route — exports GET/POST/…)
+// Anything under routes/api/ is an API route; everything else is a page (SSR).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+export async function discoverRoutes(routesDir) {
+  const root = path.resolve(routesDir);
+  const files = [];
+  await walk(root, root, files);
+  const routes = files
+    .filter((f) => /\.(mjs|js)$/.test(f.rel))
+    .map((f) => toRoute(f.rel, f.file));
+  // Most specific first: static segments beat params beat catch-all.
+  routes.sort((a, b) => b.score - a.score);
+  return routes;
+}
+
+async function walk(root, dir, out) {
+  let entries;
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) await walk(root, full, out);
+    else if (e.isFile()) out.push({ file: full, rel: path.relative(root, full).split(path.sep).join('/') });
+  }
+}
+
+function toRoute(rel, file) {
+  const clean = rel.replace(/\.(mjs|js)$/, '');
+  const isApi = clean === 'api' || clean.startsWith('api/');
+  const segs = [];
+  for (const part of clean.split('/').filter(Boolean)) {
+    if (part === 'index') continue;
+    if (part.startsWith('[...') && part.endsWith(']')) segs.push({ type: 'catchall', name: part.slice(4, -1) });
+    else if (part.startsWith('[') && part.endsWith(']')) segs.push({ type: 'param', name: part.slice(1, -1) });
+    else segs.push({ type: 'static', value: part });
+  }
+  const pattern = '/' + segs.map((s) => (s.type === 'static' ? s.value : s.type === 'param' ? `:${s.name}` : `*${s.name}`)).join('/');
+  const score = segs.reduce((acc, s) => acc + (s.type === 'static' ? 3 : s.type === 'param' ? 2 : 1), 0) * 10 + segs.length;
+  return { file, isApi, segs, pattern: pattern === '/' ? '/' : pattern, score };
+}
+
+export function matchRoute(routes, pathname) {
+  const reqSegs = pathname.replace(/\/+$/, '').split('/').filter(Boolean);
+  for (const route of routes) {
+    const params = matchSegs(route.segs, reqSegs);
+    if (params) return { route, params };
+  }
+  return null;
+}
+
+function matchSegs(segs, reqSegs) {
+  const params = {};
+  let i = 0;
+  for (const seg of segs) {
+    if (seg.type === 'catchall') {
+      params[seg.name] = reqSegs.slice(i).map(decodeURIComponent).join('/');
+      return params;
+    }
+    if (i >= reqSegs.length) return null;
+    if (seg.type === 'static') {
+      if (reqSegs[i] !== seg.value) return null;
+    } else {
+      params[seg.name] = decodeURIComponent(reqSegs[i]);
+    }
+    i++;
+  }
+  return i === reqSegs.length ? params : null;
+}

package/src/server/server.mjs

@@ -0,0 +1,147 @@
+// glashjs server — routing, SSR, and API in one Node http server.
+// ---------------------------------------------------------------------------
+// `dev: true`  -> re-discovers routes and re-imports modules each request, so
+//                 edits show up without a restart (live reload of route code).
+// `dev: false` -> caches routes; serves the built `outDir` (optimized assets,
+//                 service worker, favicons) with Brotli negotiation.
+// Every response carries the secure-by-default headers.
+import http from 'node:http';
+import { promises as fs, existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { discoverRoutes, matchRoute } from './router.mjs';
+import { renderDocument } from './html.mjs';
+import { securityHeaders } from '../security/headers.mjs';
+import { loadConfig } from '../config.mjs';
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.mjs': 'text/javascript',
+  '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp',
+  '.avif': 'image/avif', '.webmanifest': 'application/manifest+json', '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2', '.txt': 'text/plain; charset=utf-8',
+};
+const mime = (file) => MIME[path.extname(file).toLowerCase()] || 'application/octet-stream';
+
+/** Build the glashjs server. Returns { server, listen, cfg }. */
+export async function createGlashServer({ root = process.cwd(), dev = false } = {}) {
+  const cfg = await loadConfig(root);
+  const routesDir = path.resolve(root, cfg.routesDir || 'routes');
+  const outDir = path.resolve(root, cfg.outDir);
+  const secHeaders = securityHeaders(cfg.security);
+  let routes = await discoverRoutes(routesDir);
+
+  const importRoute = (file) =>
+    import(pathToFileURL(file).href + (dev ? `?t=${Date.now()}` : ''));
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+    const pathname = safeDecode(url.pathname);
+    try {
+      if (await serveStatic(res, outDir, pathname, req, secHeaders)) return;
+      if (dev) routes = await discoverRoutes(routesDir);
+      const match = matchRoute(routes, pathname);
+      if (!match) return send(res, 404, 'text/plain; charset=utf-8', 'Not found', secHeaders);
+      const mod = await importRoute(match.route.file);
+      const ctx = makeCtx(req, url, match.params);
+      return match.route.isApi
+        ? await handleApi(res, mod, req, ctx, secHeaders)
+        : await handlePage(res, mod, ctx, cfg, secHeaders);
+    } catch (err) {
+      const msg = dev ? `glashjs error:\n${err?.stack || err}` : 'Internal Server Error';
+      send(res, 500, 'text/plain; charset=utf-8', msg, secHeaders);
+    }
+  });
+
+  const listen = (port = cfg.port || 3000, host = '0.0.0.0') =>
+    new Promise((resolve) => server.listen(port, host, () => resolve({ port, host })));
+
+  return { server, listen, cfg, routes, routesDir, outDir };
+}
+
+async function handleApi(res, mod, req, ctx, secHeaders) {
+  const method = req.method.toUpperCase();
+  const handler = mod[method] || (method === 'GET' && mod.default) || mod.handler;
+  if (typeof handler !== 'function') {
+    return send(res, 405, 'application/json', JSON.stringify({ error: 'method not allowed' }), secHeaders);
+  }
+  if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) ctx.body = await readJson(req);
+  const result = await handler(ctx);
+  if (result && result.__response) {
+    return send(res, result.status || 200, result.contentType || 'application/json',
+      typeof result.body === 'string' ? result.body : JSON.stringify(result.body), { ...secHeaders, ...(result.headers || {}) });
+  }
+  send(res, 200, 'application/json', JSON.stringify(result ?? null), secHeaders);
+}
+
+async function handlePage(res, mod, ctx, cfg, secHeaders) {
+  const render = mod.default;
+  if (typeof render !== 'function') return send(res, 500, 'text/plain', 'route has no default export', secHeaders);
+  const out = await render(ctx);
+  const page = typeof out === 'string' || (out && out.__raw) ? { body: out } : (out || {});
+  const docHtml = renderDocument({
+    title: page.title || mod.title || cfg.name,
+    head: page.head || '',
+    body: page.body ?? '',
+    offline: cfg.offline,
+    animatedFavicon: !!cfg.animatedFavicon,
+  });
+  send(res, page.status || 200, 'text/html; charset=utf-8', docHtml, { ...secHeaders, ...(page.headers || {}) });
+}
+
+async function serveStatic(res, outDir, pathname, req, secHeaders) {
+  if (pathname === '/') return false; // let the index page route render
+  const rel = pathname.replace(/^\/+/, '');
+  const file = path.join(outDir, rel);
+  if (!file.startsWith(outDir + path.sep)) return false; // path traversal guard
+  const ae = String(req.headers['accept-encoding'] || '');
+  if (ae.includes('br') && existsSync(file + '.br')) {
+    const buf = await fs.readFile(file + '.br');
+    res.writeHead(200, { ...secHeaders, 'content-type': mime(file), 'content-encoding': 'br', 'cache-control': 'public, max-age=31536000, immutable' });
+    res.end(buf);
+    return true;
+  }
+  if (existsSync(file) && statSync(file).isFile()) {
+    const buf = await fs.readFile(file);
+    res.writeHead(200, { ...secHeaders, 'content-type': mime(file), 'cache-control': 'public, max-age=3600' });
+    res.end(buf);
+    return true;
+  }
+  return false;
+}
+
+function makeCtx(req, url, params) {
+  return {
+    req,
+    method: req.method,
+    url,
+    path: url.pathname,
+    params,
+    query: Object.fromEntries(url.searchParams),
+    headers: req.headers,
+    body: undefined,
+  };
+}
+
+function readJson(req) {
+  return new Promise((resolve) => {
+    let data = '';
+    req.on('data', (c) => { data += c; if (data.length > 2_000_000) req.destroy(); });
+    req.on('end', () => { try { resolve(data ? JSON.parse(data) : {}); } catch { resolve({}); } });
+    req.on('error', () => resolve({}));
+  });
+}
+
+function send(res, status, contentType, body, headers = {}) {
+  res.writeHead(status, { ...headers, 'content-type': contentType });
+  res.end(body);
+}
+
+function safeDecode(p) {
+  try { return decodeURIComponent(p); } catch { return p; }
+}
+
+/** API helper: return a typed Response from a handler. */
+export function json(body, { status = 200, headers } = {}) {
+  return { __response: true, status, contentType: 'application/json', body, headers };
+}