@transclude/core 0.1.0

package/src/server.js

@@ -0,0 +1,183 @@
+// The Hono app both servers start from.
+//
+// One function rather than two `new Hono()` calls, because the order things are
+// registered in *is* the behaviour: a guard registered after the static handler
+// does not guard a prerendered page. Two copies of that order is two servers
+// that disagree, which has happened twice in this codebase already.
+
+import { Hono } from 'hono';
+import { csrf } from 'hono/csrf';
+import { headerPolicy } from './csp.js';
+import { trimTrailingSlash } from 'hono/trailing-slash';
+
+/**
+ * `strict: false` so /about and /about/ are the same page.
+ *
+ * CSRF is on by default and the only middleware that is. This framework's whole
+ * form story is `<form method="post">`, and a cross-origin page can post one to
+ * you without any of the checks a `fetch` would have to pass. Hono's guard is
+ * scoped to exactly that hole: non-GET requests carrying one of the three
+ * content types a form element can send. JSON already needs a preflight, so it
+ * is not the way in.
+ *
+ * `middleware` is the app's own `server.js`, and it runs after, so it can add
+ * anything and cannot register itself ahead of the guard by mistake.
+ */
+const OPTIONS = new Set(['csrf', 'csp', 'trailingSlash', 'publicFiles', 'middleware']);
+
+/**
+ * @param {{ csrf?: object|boolean, csp?: object|boolean, trailingSlash?: string,
+ *   publicFiles?: Function|null, middleware?: Function|null }} [options]
+ * @returns {object} a Hono app
+ * @throws on a key it does not know
+ */
+export function baseApp(options = {}) {
+  const {
+    csrf: csrfOption = true,
+    csp: cspOption = false,
+    trailingSlash = 'never',
+    publicFiles = null,
+    middleware = null,
+  } = options;
+
+  // A key this does not know is a caller that thinks it configured something.
+  // `publicRoot` instead of `publicFiles` was exactly that: dev served no public
+  // files at all, production served them, and nothing said why.
+  const unknown = Object.keys(options).filter((key) => !OPTIONS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `[transclude] baseApp does not know ${unknown.join(', ')}. ` +
+        `It takes ${[...OPTIONS].join(', ')}.`,
+    );
+  }
+
+  if (trailingSlash !== 'never' && trailingSlash !== 'ignore') {
+    throw new Error(
+      `[transclude] trailingSlash must be 'never' or 'ignore', not ${JSON.stringify(trailingSlash)}`,
+    );
+  }
+
+  /**
+   * One decision with two halves, which is why it is a single config key rather
+   * than a router option plus a middleware the author has to remember to add.
+   *
+   * `strict: false` does not merely match /about/ as well as /about: it strips
+   * the slash from `c.req.path` before any middleware runs. Measured: with it on,
+   * `trimTrailingSlash` never fires, because the thing it looks for is gone by
+   * the time it looks. The two exclude each other.
+   *
+   * So 'never' means strict routing plus a 301 to the one URL, and every
+   * URL this framework generates is already that form: `routes/about.html` is
+   * `/about`. 'ignore' is the loose router, which answers both with 200. Two URLs
+   * for one page, and nothing emits <link rel="canonical">.
+   *
+   * `alwaysRedirect` matters because Hono's default only redirects a request that
+   * already 404'd, and a catch-all route answers before it can. `/docs/intro/`
+   * would match `/docs/:path{.+}` as `intro/` and return 200, which is the exact
+   * duplicate this setting exists to remove. Redirecting ahead of the router also
+   * spares a doomed request the route table and every middleware after this one.
+   */
+  const app = new Hono({ strict: trailingSlash === 'never' });
+  if (trailingSlash === 'never') app.use('*', trimTrailingSlash({ alwaysRedirect: true }));
+
+  if (csrfOption) app.use('*', csrf(csrfOption === true ? undefined : csrfOption));
+
+  /**
+   * The one security header with no judgement in it.
+   *
+   * Without it a browser may sniff a response's bytes and decide the declared
+   * type was wrong, so a text file an app serves can be read as HTML and a
+   * `.json` as script. Nothing legitimate depends on sniffing, which is what
+   * separates this from `X-Frame-Options` or HSTS: both of those refuse
+   * something an app may actually want, so they stay the author's to set.
+   *
+   * Before everything, so a public file and a prerendered page get it too.
+   */
+  app.use('*', async (c, next) => {
+    await next();
+    c.header('X-Content-Type-Options', 'nosniff');
+  });
+
+  // The half of the policy a `<meta>` cannot carry. It names no hash, so it is
+  // the same string for every page and costs a prerendered one nothing. Before
+  // anything that answers, so a static file gets it too.
+  const header = headerPolicy(cspOption);
+  if (header) {
+    app.use('*', async (c, next) => {
+      await next();
+      c.header(header.name, header.value);
+    });
+  }
+  if (typeof middleware === 'function') middleware(app);
+
+  // After the app's middleware, so a guard can cover these too, and before the
+  // route table, so a real file always beats a `[...path]` catch-all.
+  //
+  // A handler rather than a directory: what can serve a file is the one thing that
+  // genuinely differs between runtimes. Node hands in Hono's `serveStatic`, which
+  // does byte ranges off a disk; a runtime with no disk hands in something that
+  // reads an asset binding. This file stays free of either.
+  if (publicFiles) app.use('*', publicFiles);
+
+  return app;
+}
+
+/** Where an app puts its middleware. Relative to `appDir`. */
+export const SERVER_FILE = 'server.js';
+
+/**
+ * An endpoint is a `.js` file in the routes tree: a route with no template, no
+ * layout and no regions, which answers with a `Response` of its own.
+ *
+ *   // app/routes/api/notes.js
+ *   export const GET = () => Response.json(notes);
+ *   export const DELETE = ({ params }) => { … };
+ *
+ * Handlers are named for the method, spelled the way HTTP spells it. Uppercase
+ * is not decoration: `export const delete` is a syntax error and `DELETE` is not,
+ * not. A page's handlers are spelled the same way.
+ *
+ * Returning a `Response` is required rather than encouraged. There is no
+ * template to fall back to, and a handler that returns a bare object has almost
+ * certainly forgotten `Response.json`.
+ *
+ * @param {object} mod the endpoint module
+ * @param {object} ctx
+ * @param {string} method
+ * @returns {Promise<Response|null>} null when the module answers no such verb
+ */
+export async function runEndpoint(mod, ctx, method) {
+  const name = method.toUpperCase();
+  // Membership, not shape. `mod.HELPERS` may well be a function, and a request
+  // naming it would otherwise reach it.
+  if (!ENDPOINT_METHODS.includes(name)) return null;
+
+  const handler = mod?.[name];
+  if (typeof handler !== 'function') return null;
+
+  const out = await handler(ctx);
+  if (out instanceof Response) return out;
+
+  throw new Error(
+    `${name} answered with ${out === undefined ? 'nothing' : typeof out}, ` +
+      `not a Response. An endpoint has no template to render instead`,
+  );
+}
+
+/**
+ * The methods an endpoint can answer. `app.all` routes every one of them to it,
+ * so this is the list that decides which exports are handlers. The shim reads
+ * the same list, or a name would be dispatched and not checked, or checked and
+ * never dispatched.
+ */
+export const ENDPOINT_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'];
+
+/**
+ * What an endpoint answers, for an `Allow` header.
+ *
+ * @param {object|null|undefined} mod
+ * @returns {string[]} sorted, for an Allow header
+ */
+export function endpointMethods(mod) {
+  return ENDPOINT_METHODS.filter((name) => typeof mod?.[name] === 'function').sort();
+}

package/src/sitemap.js

@@ -0,0 +1,124 @@
+// GET /sitemap.xml, from the route table the framework already has.
+//
+// A page route with no parameters is one URL. A parameter route is as many as
+// its `paths` export names, which is the same list the build prerenders, so a
+// route that ships as files is listed without the author repeating it. Anything
+// else (a route with no `paths`, an endpoint, an error page) is not a page a
+// crawler can reach by guessing, so it is left out.
+
+/** The protocol's cap for one file. Past it the response is an index of files. */
+const LIMIT = 50000;
+
+const escape = (text) =>
+  String(text)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+
+/** `2026-07-31`, which is what a sitemap wants and what a Date will not give. */
+function day(value) {
+  if (!value) return null;
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString().slice(0, 10);
+}
+
+const excluded = (path, rules) =>
+  rules.some((rule) => (rule instanceof RegExp ? rule.test(path) : rule === path));
+
+/**
+ * Every URL the sitemap lists, in route order.
+ *
+ * `paths()` is the page's own, the one the build calls, so the two cannot
+ * disagree about which URLs exist.
+ *
+ * @param {object} manifest
+ * @param {Record<string, object>} pages
+ * @param {{ entries?: object[] | (() => object[] | Promise<object[]>),
+ *   exclude?: string[] }} [config] `entries` may be a function, so an app can
+ *   build them from its own data rather than list them
+ * @returns {Promise<Array<{ path: string, lastmod?: string }>>}
+ */
+export async function sitemapEntries(manifest, pages, { entries = [], exclude = [] } = {}) {
+  const found = [];
+
+  for (const route of manifest.routes ?? []) {
+    const page = pages[route.id];
+
+    if (!route.params.length) {
+      found.push({ path: route.pattern });
+      continue;
+    }
+
+    // A parameter route with no `paths` is server-rendered for URLs nobody has
+    // listed. Advertising the pattern would advertise `/people/:name`.
+    if (typeof page?.paths !== 'function') continue;
+
+    for (const params of (await page.paths()) ?? []) {
+      found.push({
+        path: route.pattern.replace(/:(\w+)(\{[^}]*\})?/g, (_, name) => String(params[name] ?? '')),
+      });
+    }
+  }
+
+  const extra = typeof entries === 'function' ? ((await entries()) ?? []) : entries;
+  const all = [...found, ...extra];
+
+  const seen = new Set();
+  return all.filter((entry) => {
+    if (seen.has(entry.path) || excluded(entry.path, exclude)) return false;
+    seen.add(entry.path);
+    return true;
+  });
+}
+
+function urlset(entries, hostname) {
+  const body = entries
+    .map(({ path, lastmod, changefreq, priority }) => {
+      const parts = [`<loc>${escape(new URL(path, hostname).href)}</loc>`];
+      const when = day(lastmod);
+      if (when) parts.push(`<lastmod>${when}</lastmod>`);
+      if (changefreq) parts.push(`<changefreq>${escape(changefreq)}</changefreq>`);
+      if (priority !== undefined) parts.push(`<priority>${escape(priority)}</priority>`);
+      return `<url>${parts.join('')}</url>`;
+    })
+    .join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</urlset>\n`;
+}
+
+function index(count, hostname, limit) {
+  const pages = Math.ceil(count / limit);
+  const body = Array.from({ length: pages }, (_, i) => {
+    const href = new URL(`/sitemap.xml?p=${i}`, hostname).href;
+    return `<sitemap><loc>${escape(href)}</loc></sitemap>`;
+  }).join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</sitemapindex>\n`;
+}
+
+/**
+ * The document for one request.
+ *
+ * Past the cap the bare path answers with an index and `?p=` answers with a
+ * slice, because a file over 50000 URLs is not a sitemap a crawler will read.
+ *
+ * @param {object} manifest
+ * @param {Record<string, object>} pages
+ * @param {object} config the `sitemap` block, which has to name a hostname
+ * @param {number|null} [page] which sheet, when there are more URLs than one holds
+ * @returns {Promise<string>} an XML document
+ */
+export async function sitemap(manifest, pages, config, page = null) {
+  const { hostname, limit = LIMIT } = config;
+  if (!hostname) throw new Error('[transclude] sitemap needs a hostname');
+
+  const entries = await sitemapEntries(manifest, pages, config);
+
+  if (entries.length <= limit) return urlset(entries, hostname);
+  if (page === null) return index(entries.length, hostname, limit);
+
+  const from = Number(page) * limit;
+  return urlset(entries.slice(from, from + limit), hostname);
+}

package/src/static-cache.js

@@ -0,0 +1,170 @@
+// Built output, held in memory with an ETag per representation.
+//
+// The files never change for the life of the process, because they were produced
+// at build time. The only reason to touch the disk again is if there are more of
+// them than we are willing to hold.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+const DEFAULT_MAX_BYTES = 64 * 1024 * 1024;
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.map': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.woff2': 'font/woff2',
+};
+
+/**
+ * @typedef {object} Entry
+ * @property {Buffer} body
+ * @property {string} etag
+ * @property {Map<string, { body: Buffer, etag: string }>} encodings one per content encoding
+ * @property {string} type the Content-Type to send
+ */
+
+/**
+ * @typedef {object} Store
+ * @property {number} count
+ * @property {number} bytes held in memory
+ * @property {number} onDisk left on disk because the budget ran out
+ * @property {number} encoded how many have a precompressed variant
+ * @property {Map<string, Entry|{ file: string }>} entries for the build, which
+ *   serialises these for a runtime with no filesystem
+ * @property {(pathname: string) => Entry|null} get
+ */
+
+/**
+ * Prerendered pages, keyed by the URL they stand for.
+ *
+ * @param {string} dir the directory of built pages
+ * @param {{ maxBytes?: number }} [options] how much to hold in memory
+ * @returns {Store}
+ */
+export function loadStatic(dir, options = {}) {
+  return load(dir, pageUrl, options);
+}
+
+/**
+ * Build assets, keyed by their path under the output directory.
+ *
+ * @param {string} dir
+ * @param {{ maxBytes?: number }} [options]
+ * @returns {Store}
+ */
+export function loadAssets(dir, options = {}) {
+  return load(dir, (relative) => `/${relative.split(path.sep).join('/')}`, options);
+}
+
+function load(dir, urlFor, { maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  const entries = new Map();
+  let bytes = 0;
+  let onDisk = 0;
+
+  for (const file of walk(dir)) {
+    // .br and .gz are variants of a sibling, not resources of their own.
+    if (file.endsWith('.br') || file.endsWith('.gz')) continue;
+
+    const url = urlFor(path.relative(dir, file));
+    if (url === null) continue;
+
+    const size = fs.statSync(file).size + variantSize(file);
+    if (bytes + size > maxBytes) {
+      entries.set(url, { file });
+      onDisk++;
+      continue;
+    }
+
+    bytes += size;
+    entries.set(url, read(file));
+  }
+
+  return {
+    count: entries.size,
+    bytes,
+    onDisk,
+    /** For the build, which serialises these for runtimes with no filesystem. */
+    entries,
+    encoded: [...entries.values()].filter((e) => e.encodings?.size).length,
+
+    /** Entry for a request path, or null. Trailing slashes are the same resource. */
+    get(pathname) {
+      const clean = pathname.replace(/\/+$/, '') || '/';
+      const hit = entries.get(clean);
+      if (!hit) return null;
+      return hit.body !== undefined ? hit : read(hit.file);
+    },
+  };
+}
+
+function read(file) {
+  const body = fs.readFileSync(file);
+  const etag = etagOf(body);
+  const encodings = new Map();
+
+  // Each encoding is a different set of bytes, so it needs its own ETag. Otherwise
+  // a shared cache can hand a brotli body to a client that asked for gzip, and
+  // nothing shows the mismatch until it fails to decode.
+  for (const [encoding, suffix] of [['br', '.br'], ['gzip', '.gz']]) {
+    const variant = `${file}${suffix}`;
+    if (!fs.existsSync(variant)) continue;
+    encodings.set(encoding, {
+      body: fs.readFileSync(variant),
+      etag: `${etag.slice(0, -1)}-${encoding}"`,
+    });
+  }
+
+  return { body, etag, encodings, type: TYPES[path.extname(file)] ?? 'application/octet-stream' };
+}
+
+/**
+ * A cache key for a body, not a signature.
+ *
+ * Truncated on purpose: this says whether two responses are the same bytes, and
+ * nothing trusts it for anything else. Anything that needs a digest a browser
+ * will agree with uses `crypto.subtle`.
+ *
+ * @param {Buffer|Uint8Array|string} body
+ * @returns {string} a quoted ETag
+ */
+export function etagOf(body) {
+  return `"${createHash('sha1').update(body).digest('base64url').slice(0, 20)}"`;
+}
+
+function variantSize(file) {
+  let total = 0;
+  for (const suffix of ['.br', '.gz']) {
+    const variant = `${file}${suffix}`;
+    if (fs.existsSync(variant)) total += fs.statSync(variant).size;
+  }
+  return total;
+}
+
+/** `index.html` -> `/`, `people/ada/index.html` -> `/people/ada`, `404.html` -> null. */
+function pageUrl(relative) {
+  const posix = relative.split(path.sep).join('/');
+  if (posix === 'index.html') return '/';
+  if (posix.endsWith('/index.html')) return `/${posix.slice(0, -'/index.html'.length)}`;
+  return null;
+}
+
+function walk(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, out);
+    else out.push(full);
+  }
+  return out;
+}