@transclude/core 0.13.0 → 0.14.0

package/bin/dev.js

@@ -264,17 +264,24 @@ const handleAction = async (route, c) => {
     : sendFragment(route, c, region, extra);
 };
 
-const onError = (c, err) => {
+const onError = (c, err, at = null) => {
   // Before anything reads the stack: Vite's transform means the raw one points
   // at generated code, and a reporter given that is worse than none.
   vite.ssrFixStacktrace(err);
   console.error(err);
 
-  // The same seam production has, so a reporter is exercised while you are the
-  // one looking at it rather than first on a live site.
+  // The same seam production has, with the same shape, so a reporter is
+  // exercised while you are the one looking at it rather than first on a live
+  // site. A field dev left null would read as a production bug later.
   if (typeof config.onError === 'function') {
     try {
-      config.onError(err, { request: c.req.raw, url: c.req.url, method: c.req.method });
+      config.onError(err, {
+        request: c.req.raw,
+        url: c.req.url,
+        method: c.req.method,
+        route: at ? { id: at.route.id, pattern: at.route.pattern, params: c.req.param() } : null,
+        phase: at?.phase ?? null,
+      });
     } catch (failed) {
       console.error('[transclude] onError itself threw:', failed);
     }
@@ -389,7 +396,7 @@ async function buildApp() {
         const fragment = fragmentOf(c);
         return fragment === null ? await renderPage(route, c) : await sendFragment(route, c, fragment);
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: fragmentOf(c) === null ? 'page' : 'fragment' });
       }
     });
 
@@ -400,7 +407,7 @@ async function buildApp() {
       try {
         return await handleAction(route, c);
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: 'action' });
       }
     });
   }
@@ -422,7 +429,7 @@ async function buildApp() {
           Allow: endpointMethods(mod).join(', '),
         });
       } catch (err) {
-        return onError(c, err);
+        return onError(c, err, { route, phase: 'endpoint' });
       }
     });
   }
@@ -432,7 +439,7 @@ async function buildApp() {
     try {
       return await renderPage(notFound, c, 404);
     } catch (err) {
-      return onError(c, err);
+      return onError(c, err, { route: notFound, phase: 'page' });
     }
   });
 

package/bin/serve.js

@@ -2,6 +2,7 @@
 // Node adapter. The app is in src/production.js; this listens with it.
 
 import { serve } from '@hono/node-server';
+import { drainOn } from '../src/drain.js';
 import { app, noBuild, port, summary } from '../src/production.js';
 
 if (noBuild) {
@@ -9,4 +10,8 @@ if (noBuild) {
   process.exit(1);
 }
 
-serve({ fetch: app.fetch, port }, ({ port }) => summary(port));
+const server = serve({ fetch: app.fetch, port }, ({ port }) => summary(port));
+
+// A container sends SIGTERM and waits. Node's default is to die on the spot,
+// which cuts a render that was halfway through answering.
+drainOn(server);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",

package/src/app.js

@@ -35,6 +35,11 @@ import { withDefaults } from './defaults.js';
 
 const IMMUTABLE = 'public, max-age=31536000, immutable';
 const REVALIDATE = 'public, max-age=0, must-revalidate';
+// What a personal render says instead. `public` is an explicit grant, and a
+// page that read a cookie is one visitor's. A conforming shared cache would
+// revalidate and miss on the ETag anyway; this is for the CDN whose edge rule
+// skips revalidation and would hand one visitor's page to the next.
+const PERSONAL = 'private, no-cache';
 
 // One per process rather than one per render. It holds no state between calls.
 const encoder = new TextEncoder();
@@ -220,7 +225,7 @@ export function createApp({
       revalidateTag: cache.revalidateTag,
       // Reported through `report`, so work that fails after the reader is gone
       // is not quieter than work that fails in front of them.
-      after: afterFor(c, (error) => report(error, c)),
+      after: afterFor(c, (error) => report(error, c, { route, phase: 'after' })),
       ...extra,
     };
   };
@@ -316,7 +321,7 @@ export function createApp({
         if (html === null) return c.text(`no fragment "${region}"`, 404);
         return sendRendered(c, html, ctx);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'fragment' });
       }
     });
 
@@ -369,7 +374,7 @@ export function createApp({
         if (html instanceof Response) return withEnvelope(html, ctx);
         return sendRendered(c, html, ctx);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'action' });
       }
     });
   }
@@ -391,7 +396,7 @@ export function createApp({
           Allow: endpointMethods(mod).join(', '),
         });
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'endpoint' });
       }
     });
   }
@@ -450,7 +455,7 @@ export function createApp({
         // workerd stops the rebuild when this response is sent, and the entry it
         // leaves in the in-flight map answers every later request with a dead
         // promise.
-        const after = afterFor(c, (error) => report(error, c));
+        const after = afterFor(c, (error) => report(error, c, { route, phase: 'revalidate' }));
         const html = await cache.read(cacheKey(c.req.url), window, render, after);
 
         // A miss rendered through the cache, and that render can answer with a
@@ -462,7 +467,7 @@ export function createApp({
         const ctx = last ? last.ctx : contextFor(route, c);
         return sendRendered(c, html, ctx, preload);
       } catch (err) {
-        return internalError(c, err);
+        return internalError(c, err, { route, phase: 'page' });
       }
     });
   }
@@ -475,19 +480,28 @@ export function createApp({
    * `console.error` is the default and not much of one: a real site sends this
    * to something that can page a person. `onError` is that seam, and it is given
    * the request as well, because an error with no URL and no method is most of
-   * the way to useless.
+   * the way to useless. `route` and `phase` say where: the reader starts at the
+   * loader of `people/[slug]` with `slug: 'ada'` rather than at a URL to
+   * re-derive that from. The phases are page, fragment, action, endpoint,
+   * after and revalidate.
    *
    * It is called inside a `try`. A reporter that throws would otherwise replace
    * the error being reported, which is the one failure mode a reporting hook
    * must not have.
    */
-  function report(err, c) {
+  function report(err, c, at = null) {
     if (typeof config.onError !== 'function') {
       console.error(err);
       return;
     }
     try {
-      config.onError(err, { request: c.req.raw, url: c.req.url, method: c.req.method });
+      config.onError(err, {
+        request: c.req.raw,
+        url: c.req.url,
+        method: c.req.method,
+        route: at ? { id: at.route.id, pattern: at.route.pattern, params: c.req.param() } : null,
+        phase: at?.phase ?? null,
+      });
     } catch (failed) {
       console.error(err);
       console.error('[transclude] onError itself threw:', failed);
@@ -495,8 +509,8 @@ export function createApp({
   }
 
   /** Every `catch` above. One place decides what a failed request looks like. */
-  function internalError(c, err) {
-    report(err, c);
+  function internalError(c, err, at = null) {
+    report(err, c, at);
     // No ETag and no Cache-Control: nothing about a failure should be stored or
     // revalidated, and the same bytes would be sent for an unrelated one next time.
     if (!errorPage) return c.text('Internal error', 500);
@@ -529,7 +543,10 @@ export function createApp({
     const etag = encoding ? `${base.slice(0, -1)}-${encoding}"` : base;
 
     c.header('Vary', varyOn);
-    c.header('Cache-Control', REVALIDATE);
+    // The same test that gates the held-page store. A shareable render is
+    // anyone's; a personal one has to say so, or a cache told `public` would
+    // be within its rights to believe it.
+    c.header('Cache-Control', ctx && !isShareable(html, ctx) ? PERSONAL : REVALIDATE);
     c.header('ETag', etag);
 
     // Whatever the loaders put on `ctx.response`, after the defaults above so a

package/src/cookies.js

@@ -45,7 +45,9 @@ export function cookiesOf(request, response, secret = null) {
     // `typeof` along the way said `string`, and the config carried it all the
     // way here. The only thing that said otherwise was the length. Reading
     // "needs a secret" while looking at a secret that is plainly set sends you
-    // hunting through the wiring instead of the value.
+    // hunting through the wiring instead of the value. `withDefaults` refuses
+    // the empty string at boot now; this stays for a `cookiesOf` reached
+    // without it.
     if (typeof secret === 'string') {
       throw new Error(
         `[transclude] ${what} needs a secret, and \`cookieSecret\` is set to an ` +
@@ -168,5 +170,18 @@ function overTls(request) {
  * turns the whole thing off. Set it yourself to override either way.
  */
 function withDefaults(options, request) {
-  return { path: '/', httpOnly: true, sameSite: 'Lax', secure: overTls(request), ...options };
+  const merged = { path: '/', httpOnly: true, sameSite: 'Lax', secure: overTls(request), ...options };
+
+  // Every browser drops this pair, silently, so writing it is never right.
+  // `None` is for a cookie sent cross-site, and those are Secure-only
+  // everywhere. Refused here rather than left to the browser, because a cookie
+  // that never arrives reads exactly like a bug somewhere else.
+  if (String(merged.sameSite).toLowerCase() === 'none' && !merged.secure) {
+    throw new Error(
+      `[transclude] a cookie with \`sameSite: 'None'\` needs \`secure: true\`. Every ` +
+        `browser drops the pair without it, silently. Set both, or use 'Lax'.`,
+    );
+  }
+
+  return merged;
 }

package/src/defaults.js

@@ -97,6 +97,19 @@ export function withDefaults(config = {}) {
 
   const merged = { ...DEFAULTS, ...config };
 
+  // Set but empty is refused at boot rather than at the first signed cookie,
+  // because that first read happens in production, at request time, days after
+  // the deploy that broke it. It happened: `wrangler secret put` took a blank
+  // line, so the binding existed and carried nothing. `null` stays fine, since
+  // that is how an app says it signs nothing.
+  if (merged.cookieSecret === '') {
+    throw new Error(
+      `[transclude] \`cookieSecret\` is an empty string. Whatever supplies it handed ` +
+        `over nothing: on a worker that is usually a \`wrangler secret put\` that took ` +
+        `a blank line. Set a real secret, or \`null\` for none.`,
+    );
+  }
+
   // Refused here because there are four places that render a page and only two of
   // them could fall back to a request's origin. Left to the render, `canonical`
   // would work in dev and throw in the build, which is the dev-and-production

package/src/drain.js

@@ -0,0 +1,63 @@
+// Finishing what is in flight when the platform says stop.
+//
+// A container sends SIGTERM and waits a moment before SIGKILL. Node's default
+// for SIGTERM is to die on the spot, so a render halfway through its loader
+// answers nobody, and an action may have happened with its response cut on the
+// wire. Draining instead refuses new connections, finishes what is running,
+// and leaves.
+//
+// No imports. `process` and the timers are globals, and the server arrives as
+// an argument.
+
+/**
+ * Exit cleanly on a stop signal, once the work in flight is done.
+ *
+ * `close` stops the listener and waits for every open connection. A keep-alive
+ * connection counts as open with no request on it, so idle ones are swept
+ * while the close waits; without the sweep, the first browser that ever
+ * connected would hold the wait to the cap. The cap is for a render that
+ * hangs: past it, every connection is cut and the exit code says the drain was
+ * not clean. Both timers are unref'd, so neither keeps a finished process
+ * alive.
+ *
+ * @param {object} server what `serve` returned: a `node:http` server
+ * @param {{ signals?: string[], grace?: number, sweep?: number, exit?: Function }} [options]
+ * @returns {() => void} the drain itself, so a test can run one without a signal
+ */
+export function drainOn(server, options = {}) {
+  const {
+    signals = ['SIGTERM', 'SIGINT'],
+    grace = 10_000,
+    sweep = 500,
+    exit = (code) => process.exit(code),
+  } = options;
+
+  // The cap and the close both want to be the exit. First one wins.
+  let left = false;
+  const leave = (code) => {
+    if (left) return;
+    left = true;
+    exit(code);
+  };
+
+  const drain = () => {
+    const idle = setInterval(() => server.closeIdleConnections?.(), sweep);
+    idle.unref?.();
+
+    const cap = setTimeout(() => {
+      server.closeAllConnections?.();
+      leave(1);
+    }, grace);
+    cap.unref?.();
+
+    server.close(() => {
+      clearInterval(idle);
+      clearTimeout(cap);
+      leave(0);
+    });
+    server.closeIdleConnections?.();
+  };
+
+  for (const signal of signals) process.once(signal, drain);
+  return drain;
+}

package/src/proxy.js

@@ -33,13 +33,26 @@ const DEFAULTS = {
 
 const STYLE_MODES = new Set(['keep', 'strip']);
 
+/** Every key `proxy` may set. `lookup` has no default: absent means the runtime's. */
+const KEYS = new Set([...Object.keys(DEFAULTS), 'lookup']);
+
 /**
- * Defaults filled in, and the one value worth checking checked. A misspelled
- * `styles` would keep every style attribute and say nothing, which reads exactly
- * like the setting working.
+ * Defaults filled in, and what the author wrote checked. A misspelled `maxage`
+ * would fall back to the default and say nothing, which reads exactly like the
+ * setting working. That is the failure the config's own keys refuse by name,
+ * one level up, and these keys get the same treatment.
  */
 function settings(options) {
   const config = { ...DEFAULTS, ...options };
+
+  const unknown = Object.keys(options ?? {}).filter((key) => !KEYS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `[transclude] \`proxy\` sets ${unknown.join(', ')}, which nothing reads. ` +
+        `The keys are ${[...KEYS].sort().join(', ')}.`,
+    );
+  }
+
   if (!STYLE_MODES.has(config.styles)) {
     throw new Error(
       `[transclude] proxy.styles is ${JSON.stringify(config.styles)}. It is 'keep' or 'strip'.`,
@@ -289,10 +302,12 @@ export function proxyHandler(options = {}, deps = {}) {
     try {
       const entry = await readForeign(url, config, { ...deps, store });
 
-      // No id is a question about the document rather than a piece of it.
+      // No id is a question about the document rather than a piece of it, so
+      // the answer also says what the cleaning took out. The list was already
+      // kept for exactly this; nothing read it until here.
       if (!id) {
         const { listFragments } = await import('./extract.js');
-        return json(200, { url, fragments: listFragments(entry.doc) });
+        return json(200, { url, fragments: listFragments(entry.doc), removed: entry.removed });
       }
 
       const found = resolveFragment(entry.doc, id);

package/src/rewrite.js

@@ -81,15 +81,15 @@ export function sanitize(root, { styles = 'keep' } = {}) {
           removed.push('@style');
           return false;
         }
-        return true;
-      });
-
-      for (const attr of child.attrs) {
+        // Removed rather than emptied. An empty value still means something:
+        // `href=""` names the page the fragment lands in, and `action=""`
+        // submits to it, neither of which the source wrote.
         if (!allowedUrl(child, attr)) {
           removed.push(`@${attr.name}`);
-          attr.value = '';
+          return false;
         }
-      }
+        return true;
+      });
 
       visit(child);
     }
@@ -100,7 +100,7 @@ export function sanitize(root, { styles = 'keep' } = {}) {
 }
 
 /**
- * Whether a URL-bearing attribute may keep its value.
+ * Whether a URL-bearing attribute may stay.
  *
  * `javascript:` is refused everywhere. `data:` is refused everywhere except an
  * image source, where it is ordinary and cannot navigate anything.