@ultimat3/render 20.2.1 → 22.0.0

package/src/server.ts

@@ -40,22 +40,18 @@ export { ROOT_ELEMENT_ID, renderComponent, renderToHtml } from './render-html';
 export type {
   IsrController,
   IsrControllerOptions,
-  IsrEntry,
   IsrRendered,
   IsrRenderFn,
   IsrServeResult,
-  IsrState,
-  IsrStore,
-  MemoryIsrStoreOptions,
 } from './render-isr';
 export {
   createIsrController,
-  DEFAULT_ISR_MAX_ENTRIES,
   ISR_LOCALE_PARAM,
   invalidateAndRevalidate,
   isrKey,
-  memoryIsrStore,
 } from './render-isr';
+export type { IsrEntry, IsrState, IsrStore, MemoryIsrStoreOptions } from './render-isr-store';
+export { DEFAULT_ISR_MAX_ENTRIES, memoryIsrStore } from './render-isr-store';
 export type { SsrOptions, SsrRenderFn, SsrRenderInput } from './render-ssr';
 export { renderSsr, ssrHeaders } from './render-ssr';
 export type { StaticArtifact, StaticBuildOptions, StaticRenderFn } from './render-static';

package/src/static-path.ts

@@ -0,0 +1,77 @@
+// Single responsibility: a route pattern plus `prerender()` params, as the segments a static build
+// writes. `prerender()` returns APP data, and each value becomes a directory on disk: a raw `..`
+// wrote outside the build output, and a missing param wrote a directory literally named `:slug`.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { PrerenderFailedError } from './errors';
+import type { RouteParams } from './route';
+
+/** Anything a single path segment may not carry: separators, `?` and `#` (controls: `hasControl`). */
+const UNSAFE = /[/\\?#]/;
+
+/** NUL and every C0 control, plus DEL — by code point, so no control character sits in a regex. */
+const hasControl = (text: string): boolean => {
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+};
+
+const refuse = (pattern: string, param: string, value: unknown, why: string): never => {
+  throw new PrerenderFailedError(
+    `prerender() gave ${pattern} the ${param} ${renderCauseValue(value)}, which ${why}`,
+    `return a value for every param of ${pattern} from prerender(), each one plain path text — slugify it (lowercase, [a-z0-9-]) where it comes from a title or a user`,
+  );
+};
+
+const checked = (pattern: string, param: string, segment: string): string => {
+  if (segment === '.' || segment === '..') {
+    return refuse(pattern, param, segment, 'is a dot segment — it would write outside its route');
+  }
+  if (UNSAFE.test(segment) || hasControl(segment)) {
+    return refuse(pattern, param, segment, 'carries a separator, a control character, ? or #');
+  }
+  return segment;
+};
+
+/**
+ * The raw (decoded) segments, validated. `:name` must be present and one segment; `*name` may span
+ * several (`a/b`) and may be absent, but none of its parts may be a dot segment or unsafe.
+ */
+export function filledSegments(pattern: string, params: RouteParams): readonly string[] {
+  const out: string[] = [];
+  for (const segment of pattern.split('/')) {
+    if (segment === '') continue;
+    if (segment.startsWith(':')) {
+      const name = segment.slice(1);
+      const value = Object.hasOwn(params, name) ? params[name] : undefined;
+      if (value === undefined || value === '') {
+        return refuse(
+          pattern,
+          name,
+          value,
+          'is missing — the file would be named after the pattern',
+        );
+      }
+      out.push(checked(pattern, name, value));
+      continue;
+    }
+    if (segment.startsWith('*')) {
+      const name = segment.slice(1);
+      const value = Object.hasOwn(params, name) ? (params[name] ?? '') : '';
+      for (const part of value.split('/')) if (part !== '') out.push(checked(pattern, name, part));
+      continue;
+    }
+    out.push(segment);
+  }
+  return out;
+}
+
+/** The URL form: each segment percent-encoded, as a browser's `pathname` spells it. */
+export const urlPathOf = (segments: readonly string[]): string =>
+  segments.length === 0 ? '/' : `/${segments.map(encodeURIComponent).join('/')}`;
+
+/** The file form: the DECODED segments, which is what a static server maps a URL back onto. */
+export const filePathOf = (segments: readonly string[], indexFile: string): string =>
+  [...segments, indexFile].join('/');

package/src/stream-scripts.ts

@@ -0,0 +1,18 @@
+// Single responsibility: the inline script bodies out-of-order streaming emits, as constants. Its own
+// module so a CSP builder can import the list without importing the stream renderer and its logger.
+
+export const REVEAL_BODY =
+  "window.$X=function(){document.querySelectorAll('template[data-x-hole]').forEach(function(t){" +
+  "var s=document.getElementById(t.getAttribute('data-x-hole'));if(s){s.replaceWith(t.content);t.remove()}})}";
+
+/** The one call every reveal makes. Constant, so a hash-based CSP can admit it. */
+export const REVEAL_CALL = '$X()';
+
+/**
+ * Every inline script body a streamed document can carry — two, whatever the holes. A production
+ * policy admits inline script by HASH (a `render: 'stream'` response gets no nonce), and the reveal
+ * used to be one `$X("<id>")` per hole: a body per id that no policy could list, so every reveal
+ * was blocked. The id now rides only in the escaped `data-x-hole` attribute, and `$X()` reveals
+ * every template that has arrived.
+ */
+export const STREAM_REVEAL_BODIES: readonly string[] = Object.freeze([REVEAL_BODY, REVEAL_CALL]);

package/src/surfaces.ts

@@ -47,7 +47,10 @@ export const SURFACE_SPECS = Object.freeze<Record<Surface, SurfaceSpec>>({
     defaultMode: null,
     allowedModes: [],
     jsBaselineBytes: 0,
-    mayImport: ['shared'],
+    // `app` too, measured the day this table became the rule: both tracked apps' `api/index.ts`
+    // and `api/tasks.ts` import the app slices' actions and jobs to register them. Both surfaces
+    // are server-only, so no browser bundle pays for the edge; `site` stays out.
+    mayImport: ['shared', 'app'],
     mayImportTypes: ['shared'],
   },
   shared: {
@@ -118,7 +121,11 @@ export function importGraph(
   return graph;
 }
 
-export type BoundaryRule = 'site-imports-app' | 'shared-is-a-leaf' | 'app-imports-api-at-runtime';
+export type BoundaryRule =
+  | 'site-imports-app'
+  | 'shared-is-a-leaf'
+  | 'app-imports-api-at-runtime'
+  | 'surface-imports-surface';
 
 export interface BoundaryViolation {
   readonly rule: BoundaryRule;
@@ -210,50 +217,57 @@ interface ClassifyInput {
   readonly chain: readonly string[];
 }
 
+/**
+ * One edge against `SURFACE_SPECS` — the table IS the rule. `mayImport` and `mayImportTypes` were
+ * read by nothing, so an `api → site`, `site → api` or `app → site` value import classified as no
+ * violation at all. The three pairs that had rules of their own keep them (and their codes); every
+ * other crossing the table does not allow is `surface-imports-surface`.
+ */
 function classify(i: ClassifyInput): BoundaryViolation | null {
   const chainText = i.chain.join(' → ');
+  const base = { entry: i.entry, importer: i.importer, imported: i.imported, chain: i.chain };
 
+  // Transitive, from the ENTRY: a site page reaching app/ through any number of hops.
   if (i.entrySurface === 'site' && i.importedSurface === 'app' && !i.typeOnly) {
     return {
+      ...base,
       rule: 'site-imports-app',
-      entry: i.entry,
-      importer: i.importer,
-      imported: i.imported,
-      chain: i.chain,
       cause: chainText,
       fix: `x fix boundary ${i.entry}   (or move ${i.imported} out of the shared graph)`,
     };
   }
-
-  if (
-    i.importerSurface === 'shared' &&
-    (i.importedSurface === 'app' || i.importedSurface === 'site') &&
-    !i.typeOnly
-  ) {
+  const from = i.importerSurface;
+  const to = i.importedSurface;
+  if (from === null || to === null || from === to) return null;
+  const spec = SURFACE_SPECS[from];
+  if (spec.mayImport.includes(to)) return null;
+  if (i.typeOnly && spec.mayImportTypes.includes(to)) return null;
+  // Reported above, from the site entry that reaches it — one crossing, one finding.
+  if (from === 'site' && to === 'app' && !i.typeOnly) return null;
+
+  if (from === 'shared' && !i.typeOnly) {
     return {
+      ...base,
       rule: 'shared-is-a-leaf',
-      entry: i.entry,
-      importer: i.importer,
-      imported: i.imported,
-      chain: i.chain,
       cause: `${chainText}  (shared/ is a leaf — it may not import a surface)`,
       fix: `move the shared part of ${i.imported} into shared/ and import it from ${i.importer}`,
     };
   }
-
-  if (i.importerSurface === 'app' && i.importedSurface === 'api' && !i.typeOnly) {
+  if (from === 'app' && to === 'api' && !i.typeOnly) {
     return {
+      ...base,
       rule: 'app-imports-api-at-runtime',
-      entry: i.entry,
-      importer: i.importer,
-      imported: i.imported,
-      chain: i.chain,
       cause: `${chainText}  (app/ → api/ is types-only)`,
       fix: `change to \`import type\` in ${i.importer} and call the typed client instead`,
     };
   }
-
-  return null;
+  const field = i.typeOnly ? 'mayImportTypes' : 'mayImport';
+  return {
+    ...base,
+    rule: 'surface-imports-surface',
+    cause: `${chainText}  (${from}/ may not import ${to}/${i.typeOnly ? ', even as a type' : ''}: SURFACE_SPECS.${from}.${field} is [${spec[field].join(', ')}])`,
+    fix: `move what ${i.importer} needs from ${i.imported} into shared/ and import it from there`,
+  };
 }
 
 /** Build-time gate. `x verify` and the dev server both call this. */