@bleedingdev/modern-js-runtime-extensions 3.8.3-ultramodern.2

package/src/node.ts

@@ -0,0 +1,93 @@
+import { pipeline, Transform } from 'node:stream';
+import { StringDecoder } from 'node:string_decoder';
+import { abortHeadRender, createHeadChunkProcessor } from './rendererHead';
+
+export * from './rendererHead';
+
+const toError = (reason: unknown): Error =>
+  reason instanceof Error ? reason : new Error(String(reason));
+
+export const createNodeHeadMarkerStripper = (
+  context: object,
+  terminalMarker?: string,
+): Transform => {
+  const decoder = new StringDecoder('utf8');
+  const processor = createHeadChunkProcessor(context);
+  let terminalCarry = '';
+  let sawTerminalMarker = terminalMarker === undefined;
+  const observeTerminalMarker = (output: string): string => {
+    if (!sawTerminalMarker && terminalMarker !== undefined) {
+      const observed = terminalCarry + output;
+      sawTerminalMarker = observed.includes(terminalMarker);
+      terminalCarry = observed.slice(
+        Math.max(0, observed.length - terminalMarker.length + 1),
+      );
+    }
+    return output;
+  };
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      try {
+        callback(
+          null,
+          observeTerminalMarker(
+            processor.push(
+              decoder.write(
+                Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk),
+              ),
+            ),
+          ),
+        );
+      } catch (error) {
+        callback(toError(error));
+      }
+    },
+    flush(callback) {
+      try {
+        const output = observeTerminalMarker(processor.finish(decoder.end()));
+        callback(
+          null,
+          sawTerminalMarker ? output : `${output}${terminalMarker}`,
+        );
+      } catch (error) {
+        callback(toError(error));
+      }
+    },
+    destroy(error, callback) {
+      try {
+        abortHeadRender(context);
+        callback(error);
+      } catch (abortError) {
+        callback(error ?? toError(abortError));
+      }
+    },
+  });
+};
+
+export const createOnceErrorReporter = (
+  onError?: (error: unknown) => void,
+): ((error: unknown) => void) => {
+  let reported = false;
+  return error => {
+    if (!reported) {
+      reported = true;
+      onError?.(error);
+    }
+  };
+};
+
+export const pipeNodeHeadStream = (options: {
+  source: NodeJS.ReadWriteStream;
+  destination: NodeJS.ReadWriteStream;
+  context: object;
+  terminalMarker?: string;
+  onError?: (error: Error) => void;
+}): void => {
+  const { source, destination, context, terminalMarker, onError } = options;
+  const stripper = createNodeHeadMarkerStripper(context, terminalMarker);
+  pipeline(source, stripper, destination, error => {
+    if (error !== null) {
+      onError?.(error);
+    }
+  });
+};

package/src/rendererHead.ts

@@ -0,0 +1,236 @@
+const MARKER_ATTRIBUTE = 'data-modern-helmet';
+const MARKER_PREFIX = `<template ${MARKER_ATTRIBUTE}="`;
+const MARKER_SUFFIX = '"></template>';
+const RECORD_ID_WIDTH = 12;
+const MARKER_LENGTH =
+  MARKER_PREFIX.length + 1 + 36 + RECORD_ID_WIDTH + MARKER_SUFFIX.length;
+
+export type RendererHeadMarkerProps = Record<typeof MARKER_ATTRIBUTE, string>;
+export * from './helmetCompat';
+
+type PublishRecords = (records: unknown[]) => void;
+
+type HeadTransaction = {
+  recordsByToken: Map<string, unknown>;
+  committedRecords: unknown[];
+  committedTokens: Set<string>;
+  nextRecordId: number;
+  nonce: string;
+  previousRecords: unknown[];
+  sealed: boolean;
+};
+
+type HeadState = {
+  publishedRecords: unknown[];
+  publish?: PublishRecords;
+  transaction?: HeadTransaction;
+};
+
+const HEAD_STATE = Symbol('modern.rendererHead');
+type HeadContext = { [HEAD_STATE]?: HeadState };
+
+const getState = (context: object): HeadState => {
+  const headContext = context as HeadContext;
+  let state = headContext[HEAD_STATE];
+  if (state === undefined) {
+    state = { publishedRecords: [] };
+    Object.defineProperty(headContext, HEAD_STATE, { value: state });
+  }
+  return state;
+};
+
+const formatId = (value: number): string =>
+  value.toString(36).padStart(RECORD_ID_WIDTH, '0');
+
+const createToken = (transaction: HeadTransaction): string => {
+  const token = `h${transaction.nonce}${formatId(transaction.nextRecordId)}`;
+  transaction.nextRecordId += 1;
+  return token;
+};
+
+export const beginHeadRender = (context: object): void => {
+  const state = getState(context);
+  state.transaction = {
+    recordsByToken: new Map(),
+    committedRecords: [],
+    committedTokens: new Set(),
+    nextRecordId: 0,
+    nonce: globalThis.crypto.randomUUID(),
+    previousRecords: state.publishedRecords,
+    sealed: false,
+  };
+  state.publish?.([]);
+};
+
+export const collectHeadRecord = <RecordType>(
+  context: object,
+  createRecord: () => RecordType,
+  publish: (records: RecordType[]) => void,
+): RendererHeadMarkerProps | null | undefined => {
+  const state = getState(context);
+  const transaction = state.transaction;
+  if (transaction === undefined) {
+    return undefined;
+  }
+
+  const hadPublisher = state.publish !== undefined;
+  state.publish = records => publish(records as RecordType[]);
+  if (!hadPublisher) {
+    state.publish([]);
+  }
+  if (transaction.sealed) {
+    return null;
+  }
+
+  const token = createToken(transaction);
+  transaction.recordsByToken.set(token, createRecord());
+  return { [MARKER_ATTRIBUTE]: token };
+};
+
+export const collectHeadState = <RecordType, StateType>(
+  context: object,
+  createRecord: () => RecordType,
+  derive: (records: RecordType[]) => StateType,
+  target: { helmet?: StateType },
+): RendererHeadMarkerProps | null | undefined =>
+  collectHeadRecord(context, createRecord, records => {
+    target.helmet = derive(records);
+  });
+
+const consumeMarkers = (context: object, html: string): string => {
+  const transaction = getState(context).transaction;
+  if (transaction === undefined) {
+    return html;
+  }
+
+  let cursor = 0;
+  let stripped = '';
+  while (cursor < html.length) {
+    const start = html.indexOf(MARKER_PREFIX, cursor);
+    if (start === -1) {
+      stripped += html.slice(cursor);
+      break;
+    }
+    const tokenStart = start + MARKER_PREFIX.length;
+    const end = html.indexOf(MARKER_SUFFIX, tokenStart);
+    if (end === -1) {
+      stripped += html.slice(cursor);
+      break;
+    }
+
+    const token = html.slice(tokenStart, end);
+    if (!transaction.recordsByToken.has(token)) {
+      stripped += html.slice(cursor, end + MARKER_SUFFIX.length);
+    } else {
+      stripped += html.slice(cursor, start);
+      if (!transaction.sealed && !transaction.committedTokens.has(token)) {
+        transaction.committedTokens.add(token);
+        transaction.committedRecords.push(
+          transaction.recordsByToken.get(token),
+        );
+      }
+    }
+    cursor = end + MARKER_SUFFIX.length;
+  }
+  return stripped;
+};
+
+const publish = (context: object): void => {
+  const state = getState(context);
+  const records = state.transaction?.committedRecords ?? [];
+  state.publishedRecords = records;
+  state.publish?.(records);
+};
+
+export const publishHeadRender = (context: object): void => {
+  const transaction = getState(context).transaction;
+  if (transaction !== undefined) {
+    transaction.sealed = true;
+    publish(context);
+  }
+};
+
+export const finishHeadRender = (context: object): void => {
+  const state = getState(context);
+  if (state.transaction !== undefined) {
+    if (!state.transaction.sealed) {
+      publish(context);
+    }
+    state.transaction = undefined;
+  }
+};
+
+export const completeHeadRender = (context: object, html: string): string => {
+  const stripped = consumeMarkers(context, html);
+  finishHeadRender(context);
+  return stripped;
+};
+
+export const abortHeadRender = (context: object): void => {
+  const state = getState(context);
+  const transaction = state.transaction;
+  if (transaction !== undefined) {
+    state.publishedRecords = transaction.previousRecords;
+    state.publish?.(transaction.previousRecords);
+    state.transaction = undefined;
+  }
+};
+
+const findCarryStart = (input: string): number => {
+  const windowStart = Math.max(0, input.length - MARKER_LENGTH + 1);
+  const markerStart = input.lastIndexOf(MARKER_PREFIX);
+  if (
+    markerStart >= windowStart &&
+    input.length - markerStart < MARKER_LENGTH
+  ) {
+    return markerStart;
+  }
+
+  const maxPrefixLength = Math.min(MARKER_PREFIX.length - 1, input.length);
+  for (let length = maxPrefixLength; length > 0; length -= 1) {
+    if (MARKER_PREFIX.startsWith(input.slice(-length))) {
+      return input.length - length;
+    }
+  }
+  return input.length;
+};
+
+export const createHeadChunkProcessor = (context: object) => {
+  let carry = '';
+  return {
+    push(chunk: string): string {
+      const input = carry + chunk;
+      const carryStart = findCarryStart(input);
+      const output = consumeMarkers(context, input.slice(0, carryStart));
+      carry = input.slice(carryStart);
+      return output;
+    },
+    finish(chunk = ''): string {
+      const output = completeHeadRender(context, carry + chunk);
+      carry = '';
+      return output;
+    },
+  };
+};
+
+export const createWebHeadMarkerStripper = (
+  context: object,
+): TransformStream<Uint8Array, Uint8Array> => {
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  const processor = createHeadChunkProcessor(context);
+  return new TransformStream({
+    transform(chunk, controller) {
+      const output = processor.push(decoder.decode(chunk, { stream: true }));
+      if (output) {
+        controller.enqueue(encoder.encode(output));
+      }
+    },
+    flush(controller) {
+      const output = processor.finish(decoder.decode());
+      if (output) {
+        controller.enqueue(encoder.encode(output));
+      }
+    },
+  });
+};

package/src/rscHtmlStream.ts

@@ -0,0 +1,142 @@
+/**
+ * Forked and modified from https://github.com/devongovett/rsc-html-stream.
+ * License: https://github.com/devongovett/rsc-html-stream/blob/main/LICENSE
+ */
+const encoder = new TextEncoder();
+const closingTagsPattern = /<\/body>\s*<\/html>\s*$/i;
+const closingTagsPrefixPattern =
+  /(?:<\/body>\s*(?:<\/html>\s*|<\/h(?:t(?:m(?:l>?)?)?)?|<\/?|<)?|<\/b(?:o(?:d(?:y>?)?)?)?|<\/?|<[^>]*)$/i;
+
+export const RSC_HTML_CLOSING_TAIL_LIMIT = 8 * 1024;
+
+export function injectRSCPayload(
+  rscStream: ReadableStream<Uint8Array>,
+  { injectClosingTags = true }: { injectClosingTags?: boolean } = {},
+): TransformStream<Uint8Array, Uint8Array> {
+  const decoder = new TextDecoder();
+  let retainedTail = '';
+  let committedClosingBody = false;
+  let committedHtmlClose = false;
+  let committedProbe = '';
+  let flightPromise: Promise<void> | undefined;
+
+  const startFlight = (
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ) => {
+    if (!flightPromise) {
+      flightPromise = writeRSCStream(rscStream, controller);
+      void flightPromise.catch(error => controller.error(error));
+    }
+    return flightPromise;
+  };
+
+  const enqueueHtml = (
+    value: string,
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ) => {
+    if (value) {
+      controller.enqueue(encoder.encode(value));
+    }
+  };
+
+  const processHtml = async (
+    value: string,
+    controller: TransformStreamDefaultController<Uint8Array>,
+  ) => {
+    if (!value) {
+      return;
+    }
+
+    if (committedClosingBody) {
+      const probe = committedProbe + value;
+      committedHtmlClose ||= /<\/html>/i.test(probe);
+      committedProbe = probe.slice(-6);
+      enqueueHtml(value, controller);
+      return;
+    }
+
+    const html = retainedTail + value;
+    retainedTail = '';
+    const suffix = html.match(closingTagsPrefixPattern)?.[0] ?? '';
+    const prefix = suffix ? html.slice(0, -suffix.length) : html;
+    enqueueHtml(prefix, controller);
+
+    if (!suffix) {
+      void startFlight(controller);
+      return;
+    }
+    if (suffix.length <= RSC_HTML_CLOSING_TAIL_LIMIT) {
+      retainedTail = suffix;
+      return;
+    }
+
+    await startFlight(controller);
+    if (/<\/body>/i.test(suffix)) {
+      committedClosingBody = true;
+      committedHtmlClose = /<\/html>/i.test(suffix);
+      committedProbe = suffix.slice(-6);
+    }
+    enqueueHtml(suffix, controller);
+  };
+
+  return new TransformStream({
+    async transform(chunk, controller) {
+      await processHtml(decoder.decode(chunk, { stream: true }), controller);
+    },
+    async flush(controller) {
+      await processHtml(decoder.decode(), controller);
+      await startFlight(controller);
+
+      const retainedClosingTags = closingTagsPattern.test(retainedTail);
+      enqueueHtml(retainedTail, controller);
+      if (!injectClosingTags) {
+        return;
+      }
+      if (committedClosingBody) {
+        if (!committedHtmlClose) {
+          enqueueHtml('</html>', controller);
+        }
+      } else if (!retainedClosingTags) {
+        enqueueHtml('</body></html>', controller);
+      }
+    },
+  });
+}
+
+async function writeRSCStream(
+  rscStream: ReadableStream<Uint8Array>,
+  controller: TransformStreamDefaultController<Uint8Array>,
+): Promise<void> {
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  for await (const chunk of rscStream) {
+    try {
+      writeChunk(
+        JSON.stringify(decoder.decode(chunk, { stream: true })),
+        controller,
+      );
+    } catch {
+      const base64 = JSON.stringify(btoa(String.fromCodePoint(...chunk)));
+      writeChunk(
+        `Uint8Array.from(atob(${base64}), m => m.codePointAt(0))`,
+        controller,
+      );
+    }
+  }
+
+  const remaining = decoder.decode();
+  if (remaining) {
+    writeChunk(JSON.stringify(remaining), controller);
+  }
+}
+
+function writeChunk(
+  chunk: string,
+  controller: TransformStreamDefaultController<Uint8Array>,
+) {
+  const script = `(self.__FLIGHT_DATA||=[]).push(${chunk})`;
+  controller.enqueue(
+    encoder.encode(
+      `<script>${script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1')}</script>`,
+    ),
+  );
+}

package/src/safeFailure.ts

@@ -0,0 +1,137 @@
+const SAFE_FAILURE_MESSAGES: Readonly<Record<number, string>> = {
+  500: 'Internal Server Error',
+  503: 'Service Unavailable',
+};
+
+const SAFE_FAILURE_CODES: Readonly<Record<number, string>> = {
+  500: 'INTERNAL_SERVER_ERROR',
+  503: 'SERVICE_UNAVAILABLE',
+};
+
+export type SafeFailureEnvelope = {
+  success: false;
+  error: {
+    code: string;
+    message: string;
+    status: number;
+  };
+};
+
+export type SafeFailureHttpResult = {
+  status: number;
+  body: SafeFailureEnvelope;
+  headers: Record<string, string>;
+};
+
+const readErrorProperty = (error: unknown, key: string): unknown => {
+  if (typeof error !== 'object' || error === null) {
+    return undefined;
+  }
+
+  try {
+    return (error as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+};
+
+const normalizeFailureStatus = (value: unknown): number | undefined =>
+  typeof value === 'number' &&
+  Number.isInteger(value) &&
+  value >= 400 &&
+  value <= 599
+    ? value
+    : undefined;
+
+const normalizeDelaySeconds = (value: unknown): string | undefined => {
+  if (typeof value === 'number') {
+    const seconds = Math.ceil(value);
+    return Number.isFinite(value) && value >= 0 && Number.isSafeInteger(seconds)
+      ? String(seconds)
+      : undefined;
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!/^\d+$/u.test(trimmed)) {
+      return undefined;
+    }
+    const seconds = Number(trimmed);
+    return Number.isSafeInteger(seconds) ? String(seconds) : undefined;
+  }
+
+  return undefined;
+};
+
+const normalizeHttpDate = (value: unknown): string | undefined => {
+  try {
+    if (value instanceof Date) {
+      const timestamp = Date.prototype.getTime.call(value);
+      return Number.isFinite(timestamp)
+        ? new Date(timestamp).toUTCString()
+        : undefined;
+    }
+
+    if (typeof value === 'string') {
+      const trimmed = value.trim();
+      const timestamp = Date.parse(trimmed);
+      if (Number.isFinite(timestamp)) {
+        const canonical = new Date(timestamp).toUTCString();
+        return canonical === trimmed ? canonical : undefined;
+      }
+    }
+  } catch {
+    return undefined;
+  }
+
+  return undefined;
+};
+
+const normalizeRetryAfter = (value: unknown): string | undefined =>
+  normalizeDelaySeconds(value) ?? normalizeHttpDate(value);
+
+export const getSafeFailureStatus = (error: unknown): number =>
+  normalizeFailureStatus(readErrorProperty(error, 'status')) ??
+  normalizeFailureStatus(readErrorProperty(error, 'statusCode')) ??
+  500;
+
+export const createSafeFailureHttpResult = (
+  error: unknown,
+): SafeFailureHttpResult => {
+  const status = getSafeFailureStatus(error);
+  const retryAfterMs = readErrorProperty(error, 'retryAfterMs');
+  const retryAfter =
+    status === 503
+      ? (normalizeRetryAfter(readErrorProperty(error, 'retryAfter')) ??
+        normalizeRetryAfter(readErrorProperty(error, 'retryAfterSeconds')) ??
+        normalizeRetryAfter(
+          typeof retryAfterMs === 'number' ? retryAfterMs / 1000 : undefined,
+        ))
+      : undefined;
+
+  return {
+    status,
+    body: {
+      success: false,
+      error: {
+        code: SAFE_FAILURE_CODES[status] ?? 'REQUEST_FAILED',
+        message: SAFE_FAILURE_MESSAGES[status] ?? 'Request failed',
+        status,
+      },
+    },
+    headers: {
+      'content-type': 'application/json; charset=utf-8',
+      ...(retryAfter === undefined ? {} : { 'Retry-After': retryAfter }),
+    },
+  };
+};
+
+export const createSafeJsonFailureResponse = (error: unknown): Response => {
+  const result = createSafeFailureHttpResult(error);
+  return new Response(JSON.stringify(result.body), {
+    status: result.status,
+    headers: result.headers,
+  });
+};
+
+export const createSafeFailureResponse = createSafeJsonFailureResponse;

package/src/shellStream.ts

@@ -0,0 +1,53 @@
+import { abortHeadRender, createHeadChunkProcessor } from './rendererHead';
+
+const MISSING_SHELL_MARKER_ERROR =
+  'React SSR stream ended before the shell marker';
+
+export const createConservingWebShellStream = (
+  source: ReadableStream<Uint8Array>,
+  context: object,
+  marker: string,
+  onMissingMarker?: (error: Error) => void,
+): ReadableStream<Uint8Array> => {
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  const headProcessor = createHeadChunkProcessor(context);
+  let markerCarry = '';
+  let markerFound = false;
+
+  const observeMarker = (chunk: string) => {
+    if (markerFound) {
+      return;
+    }
+    const candidate = markerCarry + chunk;
+    markerFound = candidate.includes(marker);
+    markerCarry = markerFound ? '' : candidate.slice(-(marker.length - 1));
+  };
+
+  return source.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        const decoded = decoder.decode(chunk, { stream: true });
+        observeMarker(decoded);
+        const output = headProcessor.push(decoded);
+        if (output) {
+          controller.enqueue(encoder.encode(output));
+        }
+      },
+      flush(controller) {
+        const decoded = decoder.decode();
+        observeMarker(decoded);
+        if (!markerFound) {
+          abortHeadRender(context);
+          const error = new Error(MISSING_SHELL_MARKER_ERROR);
+          onMissingMarker?.(error);
+          throw error;
+        }
+        const output = headProcessor.finish(decoded);
+        if (output) {
+          controller.enqueue(encoder.encode(output));
+        }
+      },
+    }),
+  );
+};