@bleedingdev/modern-js-renderer-core 0.0.0-bootstrap → 3.9.3-ultramodern.1

package/src/data/static.ts

@@ -0,0 +1,105 @@
+import { MAX_DATA_BYTES } from './codec';
+import { DATA_CONTENT_TYPE, DATA_STREAM_CONTENT_TYPE } from './types';
+
+/** Head marker written into documents produced by static prerendering. */
+export const PRERENDERED_DOCUMENT_META = 'ultramodern-prerendered';
+/** Directory beside a prerendered document that holds its loader payloads. */
+export const STATIC_DATA_DIRECTORY = '__ultramodern-data';
+
+/** A loader response captured at build time, replayed by the data client. */
+export interface StaticDataPayload {
+  status: number;
+  contentType: typeof DATA_CONTENT_TYPE | typeof DATA_STREAM_CONTENT_TYPE;
+  body: string;
+}
+
+function encodeRouteId(routeId: string): string {
+  let binary = '';
+  for (const byte of new TextEncoder().encode(routeId))
+    binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll('+', '-')
+    .replaceAll('/', '_')
+    .replace(/=+$/u, '');
+}
+
+/** URL path of one route's loader payload for a search-free document path. */
+export function staticDataPayloadPath(
+  pathname: string,
+  routeId: string,
+): string {
+  if (!routeId) throw new TypeError('A static data payload needs a route ID');
+  const directory = pathname.endsWith('/') ? pathname : `${pathname}/`;
+  return `${directory}${STATIC_DATA_DIRECTORY}/${encodeRouteId(routeId)}.json`;
+}
+
+/**
+ * The client reads a payload file whole before replaying it. One response
+ * wrapped as a JSON string can grow up to six times through escaping; a
+ * deferred stream's frames are bounded only one by one, so prerendering
+ * checks the whole file against the same limit.
+ */
+export const STATIC_DATA_PAYLOAD_MAX_BYTES = MAX_DATA_BYTES * 6 + 1024;
+
+const payloadTooLarge = (bytes: number | string) =>
+  new RangeError(
+    `A static loader payload of ${bytes} bytes exceeds the ${STATIC_DATA_PAYLOAD_MAX_BYTES} bytes the data client replays; reduce its (deferred) data or serve the route dynamically.`,
+  );
+
+/**
+ * Read a captured loader response with a running byte bound. Encoding only
+ * grows the body, so a body over the limit fails as soon as it crosses it,
+ * before an unbounded deferred stream is buffered.
+ */
+export async function readStaticDataPayloadBody(
+  response: Response,
+): Promise<string> {
+  if (!response.body) return '';
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let text = '';
+  for (;;) {
+    const part = await reader.read();
+    if (part.done) return text + decoder.decode();
+    bytes += part.value.byteLength;
+    if (bytes > STATIC_DATA_PAYLOAD_MAX_BYTES) {
+      const error = payloadTooLarge(`more than ${bytes}`);
+      void reader.cancel(error).catch(() => {});
+      throw error;
+    }
+    text += decoder.decode(part.value, { stream: true });
+  }
+}
+
+/** The payload file's text, or an error when the client could not read it. */
+export function encodeStaticDataPayload(payload: StaticDataPayload): string {
+  const text = JSON.stringify(payload);
+  const bytes = new TextEncoder().encode(text).byteLength;
+  if (bytes > STATIC_DATA_PAYLOAD_MAX_BYTES) throw payloadTooLarge(bytes);
+  return text;
+}
+
+export function isStaticDataPayload(
+  value: unknown,
+): value is StaticDataPayload {
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    return false;
+  const payload = value as Record<string, unknown>;
+  return (
+    Number.isInteger(payload.status) &&
+    (payload.status as number) >= 200 &&
+    (payload.status as number) <= 599 &&
+    (payload.contentType === DATA_CONTENT_TYPE ||
+      payload.contentType === DATA_STREAM_CONTENT_TYPE) &&
+    typeof payload.body === 'string'
+  );
+}
+
+/** Whether the current browser document was emitted by static prerendering. */
+export function isPrerenderedDocument(): boolean {
+  return (
+    typeof document !== 'undefined' &&
+    document.querySelector(`meta[name="${PRERENDERED_DOCUMENT_META}"]`) !== null
+  );
+}

package/src/data/tree.ts

@@ -0,0 +1,244 @@
+import type { SerovalJSON } from 'seroval';
+
+const MAX_NODES = 20_000;
+const MAX_DEPTH = 300;
+type NodeRecord = Record<string, unknown>;
+
+function record(value: unknown): NodeRecord {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    (Object.getPrototypeOf(value) !== Object.prototype &&
+      Object.getPrototypeOf(value) !== null)
+  ) {
+    throw new TypeError('Malformed public data tree record');
+  }
+  return value as NodeRecord;
+}
+
+function exactFields(value: NodeRecord, fields: string[]): void {
+  if (
+    Reflect.ownKeys(value).length !== fields.length ||
+    fields.some(field => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, field);
+      return descriptor === undefined || !('value' in descriptor);
+    })
+  ) {
+    throw new TypeError('Malformed public data node fields');
+  }
+}
+
+function integer(value: unknown, maximum: number): value is number {
+  return (
+    typeof value === 'number' &&
+    Number.isInteger(value) &&
+    value >= 0 &&
+    value <= maximum
+  );
+}
+
+function nodeArray(value: unknown): unknown[] {
+  if (
+    !Array.isArray(value) ||
+    Object.getPrototypeOf(value) !== Array.prototype ||
+    value.length > MAX_NODES ||
+    Reflect.ownKeys(value).length !== value.length + 1
+  ) {
+    throw new TypeError('Malformed or oversized public data node array');
+  }
+  for (let index = 0; index < value.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor || !('value' in descriptor)) {
+      throw new TypeError('Public data node arrays must be dense values');
+    }
+  }
+  return value;
+}
+
+function pairs(value: unknown): { k: unknown[]; v: unknown[] } {
+  const entry = record(value);
+  exactFields(entry, ['k', 'v']);
+  const keys = nodeArray(entry.k);
+  const values = nodeArray(entry.v);
+  if (keys.length !== values.length) {
+    throw new TypeError('Public data keys and values have different lengths');
+  }
+  return { k: keys, v: values };
+}
+
+/** Validate inert, pure-data Seroval JSON before the decoder can coerce it. */
+export function validateSerializedData(
+  value: unknown,
+): asserts value is SerovalJSON {
+  const tree = record(value);
+  exactFields(tree, ['t', 'f', 'm']);
+  if (!integer(tree.f, 127)) {
+    throw new TypeError('Malformed public data feature flags');
+  }
+  const metadata = nodeArray(tree.m);
+  if (
+    metadata.some(id => !integer(id, MAX_NODES)) ||
+    new Set(metadata).size !== metadata.length
+  ) {
+    throw new TypeError('Malformed public data reference metadata');
+  }
+
+  const declarations = new Map<number, number>();
+  let count = 0;
+  const declare = (id: unknown, tag: number): void => {
+    if (!integer(id, MAX_NODES)) {
+      throw new TypeError('Malformed public data reference id');
+    }
+    if (declarations.has(id)) {
+      throw new TypeError('Duplicate public data reference id');
+    }
+    declarations.set(id, tag);
+  };
+  const visit = (input: unknown, depth: number, mapSentinel = false): void => {
+    if (++count > MAX_NODES || depth > MAX_DEPTH) {
+      throw new TypeError('Public data tree exceeds its size or depth limit');
+    }
+    const node = record(input);
+    const tagDescriptor = Object.getOwnPropertyDescriptor(node, 't');
+    if (
+      !tagDescriptor ||
+      !('value' in tagDescriptor) ||
+      !integer(tagDescriptor.value, 26)
+    ) {
+      throw new TypeError('Malformed public data node tag');
+    }
+    const tag = tagDescriptor.value as number;
+
+    if (mapSentinel && tag !== 4 && tag !== 26) {
+      throw new TypeError('Malformed public data Map sentinel');
+    }
+    switch (tag) {
+      case 0:
+        exactFields(node, ['t', 's']);
+        if (typeof node.s !== 'number' || !Number.isFinite(node.s)) {
+          throw new TypeError('Malformed public data number');
+        }
+        return;
+      case 1:
+        exactFields(node, ['t', 's']);
+        if (typeof node.s !== 'string')
+          throw new TypeError('Malformed public data string');
+        return;
+      case 2:
+        exactFields(node, ['t', 's']);
+        if (!integer(node.s, 7))
+          throw new TypeError('Malformed public data constant');
+        return;
+      case 3:
+        exactFields(node, ['t', 's']);
+        if (
+          typeof node.s !== 'string' ||
+          node.s.length > 10_000 ||
+          !/^-?(?:0|[1-9]\d*)$/.test(node.s)
+        ) {
+          throw new TypeError('Malformed public data bigint');
+        }
+        return;
+      case 4: {
+        exactFields(node, ['t', 'i']);
+        if (!integer(node.i, MAX_NODES) || !declarations.has(node.i)) {
+          throw new TypeError('Missing or forward public data reference');
+        }
+        if ((declarations.get(node.i) === 26) !== mapSentinel) {
+          throw new TypeError(
+            'Public data references a Map sentinel as a value',
+          );
+        }
+        return;
+      }
+      case 5:
+        exactFields(node, ['t', 'i', 's']);
+        if (typeof node.s !== 'string')
+          throw new TypeError('Malformed public data date');
+        if (node.s !== '') {
+          const timestamp = new Date(node.s);
+          if (
+            !Number.isFinite(timestamp.getTime()) ||
+            timestamp.toISOString() !== node.s
+          ) {
+            throw new TypeError('Malformed public data date');
+          }
+        }
+        declare(node.i, tag);
+        return;
+      case 6:
+        exactFields(node, ['t', 'i', 'c', 'm']);
+        if (
+          typeof node.c !== 'string' ||
+          typeof node.m !== 'string' ||
+          !/^[dgimsuvy]*$/.test(node.m) ||
+          new Set(node.m).size !== node.m.length ||
+          (node.m.includes('u') && node.m.includes('v'))
+        ) {
+          throw new TypeError('Malformed public data regular expression');
+        }
+        declare(node.i, tag);
+        return;
+      case 7:
+        exactFields(node, ['t', 'i', 'a']);
+        declare(node.i, tag);
+        for (const item of nodeArray(node.a)) visit(item, depth + 1);
+        return;
+      case 8: {
+        exactFields(node, ['t', 'i', 'e', 'f']);
+        declare(node.i, tag);
+        const entries = pairs(node.e);
+        // The native decoder visits each key then its value, not all keys first.
+        for (let index = 0; index < entries.k.length; index++) {
+          visit(entries.k[index], depth + 1);
+          visit(entries.v[index], depth + 1);
+        }
+        visit(node.f, depth + 1, true);
+        return;
+      }
+      case 9:
+        exactFields(node, ['t', 'i', 'a', 'o']);
+        if (!integer(node.o, 3))
+          throw new TypeError('Malformed public data object flags');
+        declare(node.i, tag);
+        for (const item of nodeArray(node.a)) {
+          // Seroval encodes a sparse array hole as the literal 0, not a node.
+          if (item === 0) {
+            if (++count > MAX_NODES)
+              throw new TypeError('Public data tree exceeds its size limit');
+          } else visit(item, depth + 1);
+        }
+        return;
+      case 10:
+      case 11: {
+        exactFields(node, ['t', 'i', 'p', 'o']);
+        if (!integer(node.o, 3))
+          throw new TypeError('Malformed public data object flags');
+        declare(node.i, tag);
+        const properties = pairs(node.p);
+        if (
+          properties.k.some(key => typeof key !== 'string') ||
+          new Set(properties.k).size !== properties.k.length
+        ) {
+          throw new TypeError('Malformed or duplicate public data object keys');
+        }
+        for (const item of properties.v) visit(item, depth + 1);
+        return;
+      }
+      case 26:
+        exactFields(node, ['t', 'i', 's']);
+        if (!mapSentinel || node.s !== 0) {
+          throw new TypeError('Unsupported public data special reference');
+        }
+        declare(node.i, tag);
+        return;
+      default:
+        throw new TypeError('Unsupported public data node');
+    }
+  };
+
+  visit(tree.t, 0);
+  if (metadata.some(id => !declarations.has(id as number))) {
+    throw new TypeError('Missing public data metadata reference');
+  }
+}

package/src/data/types.ts

@@ -0,0 +1,98 @@
+import type { RendererIdentity } from '../identity';
+
+export const DATA_PROTOCOL_VERSION = 1 as const;
+export const DATA_CONTENT_TYPE = 'application/vnd.ultramodern.data+json';
+export const DATA_STREAM_CONTENT_TYPE =
+  'application/vnd.ultramodern.data-stream+json';
+export const LOADER_ID_PARAM = '__loader';
+export const DIRECT_PARAM = '__ssrDirect';
+
+export type DataOperation = 'loader' | 'action';
+export type DataHeaders = [string, string][];
+
+export interface DataResponseMetadata {
+  status: number;
+  statusText: string;
+  headers: DataHeaders;
+  cachePolicy: 'no-store' | 'private' | 'public';
+}
+
+export interface PublicDataError {
+  name: string;
+  message: string;
+  stack?: string;
+}
+
+export type DataOutcome =
+  | { kind: 'success'; value: unknown; response: DataResponseMetadata }
+  | { kind: 'redirect'; location: string; response: DataResponseMetadata }
+  | {
+      kind: 'not-found';
+      value: unknown;
+      thrown: boolean;
+      response: DataResponseMetadata;
+    }
+  | {
+      kind: 'error';
+      error: PublicDataError;
+      data?: unknown;
+      thrown: boolean;
+      response: DataResponseMetadata;
+    }
+  | {
+      kind: 'deferred';
+      critical: Record<string, unknown>;
+      deferred: Record<string, Promise<unknown>>;
+      response: DataResponseMetadata;
+    };
+
+export interface DataHandlerInput<Context = unknown> {
+  request: Request;
+  routeId: string;
+  params: Readonly<Record<string, string>>;
+  context: Context;
+}
+
+export type DataHandler<Context = unknown> = (
+  input: DataHandlerInput<Context>,
+) => unknown | Promise<unknown>;
+
+/** The native router supplies an authorized match, never a shared matcher. */
+export interface SelectedDataRoute<Context = unknown> {
+  routeId: string;
+  params: Readonly<Record<string, string>>;
+  handler: DataHandler<Context>;
+}
+
+export interface DataWireEnvelope {
+  version: typeof DATA_PROTOCOL_VERSION;
+  identity: RendererIdentity;
+  routeId: string;
+  operation: DataOperation;
+  outcome: PublicDataOutcome;
+  deferredKeys?: string[];
+}
+
+/** Header values and request-owned context never enter a public payload. */
+export type PublicDataOutcome =
+  | { kind: 'success'; value: unknown; status: number }
+  | { kind: 'redirect'; location: string; status: number }
+  | { kind: 'not-found'; value: unknown; thrown: boolean; status: number }
+  | {
+      kind: 'error';
+      error: PublicDataError;
+      data?: unknown;
+      thrown: boolean;
+      status: number;
+    };
+
+/** A deferred body is successful only when its terminal framing completes. */
+export type DecodedDataOutcome = PublicDataOutcome & {
+  completion?: Promise<void>;
+};
+
+export type DataStreamFrame =
+  | { type: 'initial'; envelope: DataWireEnvelope }
+  | { type: 'resolve'; key: string; value: unknown }
+  | { type: 'reject'; key: string; error: PublicDataError }
+  | { type: 'complete' };