@transclude/core 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.7.0",
+  "version": "0.8.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/skills/transclude/references/server.md

@@ -154,6 +154,23 @@ something built on Wasm fails there and nowhere else. A prerendered page never
 runs its loader in production, so this stays hidden until something asks for a
 fragment.
 
+### worker.js
+
+```js
+import { workerFrom } from '@transclude/core/worker';
+import * as bundle from './dist/server/assets.js';
+import * as entry from './dist/server/entry.js';
+import manifest from './dist/routes.json';
+import config from './transclude.config.js';
+
+export default workerFrom({ config, manifest, entry, bundle });
+```
+
+The imports stay in the app: a bundler needs a literal path. `workerFrom` builds
+the app on the first request, which is when `env` exists, and takes
+`cookieSecret` from `env.COOKIE_SECRET`. For anything else, call `createApp`
+from `@transclude/core/app` directly.
+
 ### Bindings
 
 `ctx` has no `env`. It carries nothing that names one runtime, and `env` names

package/src/app.js

@@ -30,6 +30,7 @@ import { pickEncoding } from './negotiate.js';
 import { baseApp, endpointMethods, runEndpoint } from './server.js';
 import { cookiesOf } from './cookies.js';
 import { afterFor } from './after.js';
+import { withDefaults } from './defaults.js';
 
 const IMMUTABLE = 'public, max-age=31536000, immutable';
 const REVALIDATE = 'public, max-age=0, must-revalidate';
@@ -143,7 +144,11 @@ function isShareable(html, ctx) {
  * @returns {object} a Hono app, ready to serve
  */
 export function createApp({
-  config,
+  // Filled in here rather than by the caller, because only one of the four
+  // runtimes has a `loadProject` to fill them in on the way. A worker imports
+  // `transclude.config.js` and hands over exactly what the author wrote, so
+  // every key they left out was undefined until this line.
+  config: written,
   manifest,
   pages,
   endpoints = {},
@@ -164,6 +169,7 @@ export function createApp({
   // it the proxy's allowlist is the whole defense.
   lookup = null,
 }) {
+  const config = withDefaults(written);
   const cache = createCache(config.cache);
 
   // One resolver for the app, so several pages including the same document read

package/src/cookies.js

@@ -39,6 +39,21 @@ export function cookiesOf(request, response, secret = null) {
 
   const requireSecret = (what) => {
     if (secret) return secret;
+
+    // Set-but-empty is worth its own sentence. It happened on a real deploy:
+    // `wrangler secret put` took a blank line, so the binding existed, every
+    // `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.
+    if (typeof secret === 'string') {
+      throw new Error(
+        `[transclude] ${what} needs a secret, and \`cookieSecret\` is set to an ` +
+          `empty string. Whatever supplies it handed over nothing: on a worker that ` +
+          `is usually a \`wrangler secret put\` that took a blank line`,
+      );
+    }
+
     throw new Error(
       `[transclude] ${what} needs a secret. Set \`cookieSecret\` in ` +
         `transclude.config.js (read it from the environment there, not from a literal)`,

package/src/defaults.js

@@ -0,0 +1,51 @@
+// What a config means when it does not say.
+//
+// Split out of `project.js` because that file reads a disk and this has to run
+// where there is no disk. `loadProject` is Node's way in, and a worker has no
+// equivalent: it imports `transclude.config.js` directly, so the object reaching
+// `createApp` there is exactly what the author wrote and nothing more.
+//
+// That gap was live for a while. `fragmentParam` was only ever filled in by
+// `loadProject`, so on workerd `config.fragmentParam` was undefined, the check
+// for it read as "no parameter configured", and every `?fragment=` request was
+// answered with the whole document. A swap then wrote a second copy of the page
+// into the element it was meant to replace. It looked like a compiler bug and it
+// was a missing default.
+//
+// Applied in `createApp` rather than in each entry, so there is one place and no
+// runtime can skip it.
+//
+// No `node:` imports.
+
+/** Every key with a value, and the value it takes when the config is quiet. */
+export const DEFAULTS = {
+  appDir: 'app',
+  routesDir: 'routes',
+  elementsDir: 'elements',
+  publicDir: 'public',
+  iconsDir: 'icons',
+  outDir: 'dist',
+  typesFile: 'app/transclude-env.d.ts',
+  stylesheet: null,
+  lang: 'en',
+  fragmentParam: 'fragment',
+  trailingSlash: 'never',
+  strict: false,
+  csrf: true,
+  csp: false,
+  speculate: false,
+};
+
+/**
+ * A config with every default filled in.
+ *
+ * A key the author wrote wins, including one written as `null` or `false`. Only
+ * an absent key takes the default, which is what lets `fragmentParam: null` turn
+ * the parameter off rather than quietly turning it back on.
+ *
+ * @param {object} [config] whatever `transclude.config.js` exported
+ * @returns {object} the same keys, plus the ones it did not mention
+ */
+export function withDefaults(config = {}) {
+  return { ...DEFAULTS, ...config };
+}

package/src/project.js

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { withDefaults } from './defaults.js';
 
 export const CONFIG_FILE = 'transclude.config.js';
 
@@ -80,24 +81,11 @@ export function findRoot(from = process.cwd()) {
  *
  * `port` is not here. `portOf` already answers it, and it reads the environment
  * first, which a plain default cannot do.
+ *
+ * They live in `defaults.js` rather than here, because a worker has no
+ * `loadProject` and needs the same answers. `createApp` applies them for every
+ * runtime, and this file is only Node's way in.
  */
-const DEFAULTS = {
-  appDir: 'app',
-  routesDir: 'routes',
-  elementsDir: 'elements',
-  publicDir: 'public',
-  iconsDir: 'icons',
-  outDir: 'dist',
-  typesFile: 'app/transclude-env.d.ts',
-  stylesheet: null,
-  lang: 'en',
-  fragmentParam: 'fragment',
-  trailingSlash: 'never',
-  strict: false,
-  csrf: true,
-  csp: false,
-  speculate: false,
-};
 
 /**
  * The root and its config together, because nothing needs one without the other.
@@ -117,7 +105,7 @@ export async function loadProject(from = process.cwd()) {
     throw new Error(`[transclude] ${CONFIG_FILE} must export a config object as its default`);
   }
   assertNoSplitDirs(config, file);
-  return { root, config: { ...DEFAULTS, ...config }, configFile: file };
+  return { root, config: withDefaults(config), configFile: file };
 }
 
 /**

package/src/worker.js

@@ -5,6 +5,8 @@
 // is WebCrypto and therefore async. Those are runtime facts, so they live here.
 // Which modules to import is an app fact, so that stays in the app's own entry.
 
+import { createApp } from './app.js';
+
 /** base64 in, bytes out. `atob` is in every runtime that has no `Buffer`. */
 const decode = (base64) => Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
 
@@ -85,3 +87,58 @@ export async function hash(body) {
   for (const byte of bytes) base64 += String.fromCharCode(byte);
   return `"${btoa(base64).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '').slice(0, 20)}"`;
 }
+
+/**
+ * The whole worker, for an app that wants the ordinary wiring.
+ *
+ * Nine apps in this repository wrote the same forty lines: parse the manifest,
+ * wrap each byte map, build the app on the first request because that is when
+ * `env` exists, and hand the request on. The imports have to stay in the app's
+ * own file, because a bundler needs a literal path to follow. The wiring does
+ * not, and this is it.
+ *
+ * `cookieSecret` comes from `env.COOKIE_SECRET` when there is one, which is the
+ * only piece of config a worker cannot read at import time. An app needing
+ * something else calls `createApp` itself: this covers the common shape rather
+ * than every shape.
+ *
+ * @param {object} options
+ * @param {object} options.config the app's `transclude.config.js`
+ * @param {string|object} options.manifest `dist/routes.json`, text or parsed
+ * @param {object} options.entry everything `dist/server/entry.js` exports
+ * @param {object} options.bundle everything `dist/server/assets.js` exports
+ * @returns {{ fetch: (request: Request, env: object, ctx: object) => Response|Promise<Response> }}
+ */
+export function workerFrom({ config, manifest, entry, bundle }) {
+  // Built on the first request rather than at import, because that is when
+  // `env` exists. There is no `process.env` here, so a secret read any earlier
+  // is undefined, and signing refuses.
+  let app = null;
+
+  return {
+    fetch(request, env, ctx) {
+      app ??= createApp({
+        config: { ...config, cookieSecret: env.COOKIE_SECRET ?? config.cookieSecret },
+        // There is no JSON module type in Workers, so the manifest usually
+        // arrives as a string. Used as an object it gives a route table of
+        // `undefined` and a site of 404s that looks exactly like a routing bug.
+        manifest: typeof manifest === 'string' ? JSON.parse(manifest) : manifest,
+        pages: entry.pages,
+        endpoints: entry.endpoints,
+        middleware: entry.middleware,
+        statics: bytesFrom(bundle.statics),
+        assets: bytesFrom(bundle.assets),
+        publicFiles: fileHandler(bundle.publicFiles),
+        notFound: pageEntry(bundle.notFound),
+        errorPage: pageEntry(bundle.errorPage),
+        hash,
+        // The edge compresses. Doing it here would be a second pass over bytes
+        // already going through one.
+        compress: null,
+        precache: bundle.precache,
+      });
+
+      return app.fetch(request, env, ctx);
+    },
+  };
+}