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

package/tests/rendererHead.test.ts

@@ -0,0 +1,299 @@
+import { PassThrough, Readable } from 'node:stream';
+import {
+  abortHeadRender,
+  beginHeadRender,
+  collectHeadRecord,
+  completeHeadRender,
+  createHeadChunkProcessor,
+  createWebHeadMarkerStripper,
+  publishHeadRender,
+} from '../src';
+import {
+  createNodeHeadMarkerStripper,
+  createOnceErrorReporter,
+  pipeNodeHeadStream,
+} from '../src/node';
+
+const marker = (props: Record<string, string>) =>
+  `<template data-modern-helmet="${props['data-modern-helmet']}"></template>`;
+
+describe('renderer head transactions', () => {
+  it('commits only markers observed in completed output', () => {
+    const context = {};
+    let published: string[] = [];
+    beginHeadRender(context);
+    const committed = collectHeadRecord(
+      context,
+      () => 'committed',
+      records => {
+        published = records;
+      },
+    )!;
+    collectHeadRecord(
+      context,
+      () => 'abandoned',
+      records => {
+        published = records;
+      },
+    );
+
+    expect(completeHeadRender(context, `a${marker(committed)}b`)).toBe('ab');
+    expect(published).toEqual(['committed']);
+  });
+
+  it('preserves user templates that are not current transaction markers', () => {
+    const context = {};
+    beginHeadRender(context);
+    const userTemplate =
+      '<template data-modern-helmet="h00000000-0000-0000-0000-000000000000000000000000"></template>';
+
+    expect(completeHeadRender(context, userTemplate)).toBe(userTemplate);
+  });
+
+  it('does not retain ordinary streaming content', () => {
+    const context = {};
+    beginHeadRender(context);
+    const processor = createHeadChunkProcessor(context);
+    const content = 'x'.repeat(128 * 1024);
+
+    expect(processor.push(content)).toBe(content);
+    expect(processor.finish()).toBe('');
+  });
+
+  it('strips markers split across chunks without corrupting unicode', () => {
+    const sampleContext = {};
+    beginHeadRender(sampleContext);
+    const sampleProps = collectHeadRecord(
+      sampleContext,
+      () => 'head',
+      () => {},
+    )!;
+    const sampleHtml = `č${marker(sampleProps)}尾`;
+
+    for (let split = 1; split < sampleHtml.length; split += 1) {
+      const context = {};
+      beginHeadRender(context);
+      const props = collectHeadRecord(
+        context,
+        () => 'head',
+        () => {},
+      )!;
+      const html = `č${marker(props)}尾`;
+      const processor = createHeadChunkProcessor(context);
+      expect(
+        processor.push(html.slice(0, split)) +
+          processor.finish(html.slice(split)),
+      ).toBe('č尾');
+    }
+  });
+
+  it('freezes the published shell and ignores late records', () => {
+    const context = {};
+    let published: string[] = [];
+    beginHeadRender(context);
+    const shell = collectHeadRecord(
+      context,
+      () => 'shell',
+      records => {
+        published = records;
+      },
+    )!;
+    const late = collectHeadRecord(
+      context,
+      () => 'late',
+      records => {
+        published = records;
+      },
+    )!;
+    const processor = createHeadChunkProcessor(context);
+    expect(processor.push(marker(shell))).toBe('');
+    publishHeadRender(context);
+
+    expect(
+      collectHeadRecord(
+        context,
+        () => 'late',
+        records => {
+          published = records;
+        },
+      ),
+    ).toBeNull();
+    expect(processor.finish(marker(late))).toBe('');
+    expect(published).toEqual(['shell']);
+  });
+
+  it('clears the previous snapshot while rendering and restores it on abort', () => {
+    const context = {};
+    let published: string[] = [];
+    const publish = (records: string[]) => {
+      published = records;
+    };
+
+    beginHeadRender(context);
+    const previous = collectHeadRecord(context, () => 'previous', publish)!;
+    completeHeadRender(context, marker(previous));
+    expect(published).toEqual(['previous']);
+
+    beginHeadRender(context);
+    expect(published).toEqual([]);
+    collectHeadRecord(context, () => 'provisional', publish);
+    abortHeadRender(context);
+    expect(published).toEqual(['previous']);
+  });
+
+  it('strips split markers from a web byte stream', async () => {
+    const context = {};
+    let published: string[] = [];
+    beginHeadRender(context);
+    const props = collectHeadRecord(
+      context,
+      () => 'web',
+      records => {
+        published = records;
+      },
+    )!;
+    const html = `č${marker(props)}尾`;
+    const encoder = new TextEncoder();
+    const encoded = encoder.encode(html);
+    const source = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(encoded.slice(0, 1));
+        controller.enqueue(encoded.slice(1, 17));
+        controller.enqueue(encoded.slice(17));
+        controller.close();
+      },
+    });
+
+    const output = await new Response(
+      source.pipeThrough(createWebHeadMarkerStripper(context)),
+    ).text();
+    expect(output).toBe('č尾');
+    expect(published).toEqual(['web']);
+  });
+
+  it('strips split markers from a Node stream', async () => {
+    const context = {};
+    let published: string[] = [];
+    beginHeadRender(context);
+    const props = collectHeadRecord(
+      context,
+      () => 'node',
+      records => {
+        published = records;
+      },
+    )!;
+    const html = `č${marker(props)}尾`;
+    const encoded = Buffer.from(html);
+    const stripper = createNodeHeadMarkerStripper(context);
+    const output = new Promise<string>((resolve, reject) => {
+      let rendered = '';
+      stripper.setEncoding('utf8');
+      stripper.on('data', chunk => {
+        rendered += chunk;
+      });
+      stripper.on('end', () => resolve(rendered));
+      stripper.on('error', reject);
+    });
+    stripper.write(encoded.subarray(0, 1));
+    stripper.write(encoded.subarray(1, 17));
+    stripper.end(encoded.subarray(17));
+
+    await expect(output).resolves.toBe('č尾');
+    expect(published).toEqual(['node']);
+  });
+
+  it('injects one missing terminal marker without truncating multichunk UTF-8', async () => {
+    const context = {};
+    const terminalMarker = '<!-- shell stream end -->';
+    const prefix = Buffer.from('x'.repeat(9 * 1024));
+    const unicodeTail = Buffer.from('č尾');
+    const input = Buffer.concat([prefix, unicodeTail]);
+    beginHeadRender(context);
+    const stripper = createNodeHeadMarkerStripper(context, terminalMarker);
+    const output = new Promise<string>((resolve, reject) => {
+      let rendered = '';
+      stripper.setEncoding('utf8');
+      stripper.on('data', chunk => {
+        rendered += chunk;
+      });
+      stripper.on('end', () => resolve(rendered));
+      stripper.on('error', reject);
+    });
+    stripper.write(input.subarray(0, prefix.length + 1));
+    stripper.write(input.subarray(prefix.length + 1, prefix.length + 3));
+    stripper.end(input.subarray(prefix.length + 3));
+
+    await expect(output).resolves.toBe(
+      `${input.toString('utf8')}${terminalMarker}`,
+    );
+  });
+
+  it('does not duplicate a split terminal marker or corrupt its tail', async () => {
+    const context = {};
+    const terminalMarker = '<!-- shell stream end -->';
+    const input = Buffer.from(`shell${terminalMarker}č尾`);
+    const markerOffset = Buffer.byteLength('shell') + 7;
+    beginHeadRender(context);
+    const stripper = createNodeHeadMarkerStripper(context, terminalMarker);
+    const output = new Promise<string>((resolve, reject) => {
+      let rendered = '';
+      stripper.setEncoding('utf8');
+      stripper.on('data', chunk => {
+        rendered += chunk;
+      });
+      stripper.on('end', () => resolve(rendered));
+      stripper.on('error', reject);
+    });
+    stripper.write(input.subarray(0, markerOffset));
+    stripper.write(input.subarray(markerOffset, input.length - 1));
+    stripper.end(input.subarray(input.length - 1));
+
+    await expect(output).resolves.toBe(input.toString('utf8'));
+  });
+
+  it('rejects the destination and reports a source error exactly once', async () => {
+    const source = new PassThrough();
+    const destination = new PassThrough();
+    const output = new Response(
+      Readable.toWeb(destination) as ReadableStream<Uint8Array>,
+    ).text();
+    const onError = rstest.fn();
+    pipeNodeHeadStream({ source, destination, context: {}, onError });
+
+    source.destroy(new Error('source failed'));
+
+    await expect(output).rejects.toThrow('source failed');
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects the destination and reports a stripper error exactly once', async () => {
+    const source = new PassThrough();
+    const destination = new PassThrough();
+    const output = new Response(
+      Readable.toWeb(destination) as ReadableStream<Uint8Array>,
+    ).text();
+    const onError = rstest.fn();
+    pipeNodeHeadStream({
+      source,
+      destination,
+      context: Object.freeze({}),
+      onError,
+    });
+
+    source.end('trigger frozen-context failure');
+
+    await expect(output).rejects.toThrow('object is not extensible');
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports a shared render and stream failure only once', () => {
+    const onError = rstest.fn();
+    const reportError = createOnceErrorReporter(onError);
+    const failure = new Error('shared failure');
+
+    reportError(failure);
+    reportError(failure);
+
+    expect(onError).toHaveBeenCalledExactlyOnceWith(failure);
+  });
+});

package/tests/rscHtmlStream.test.ts

@@ -0,0 +1,153 @@
+import {
+  injectRSCPayload,
+  RSC_HTML_CLOSING_TAIL_LIMIT,
+} from '../src/rscHtmlStream';
+
+const encoder = new TextEncoder();
+const flight = '<script>(self.__FLIGHT_DATA||=[]).push("payload")</script>';
+
+async function readStream(stream: ReadableStream<Uint8Array>) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let value = '';
+  for (;;) {
+    const result = await reader.read();
+    if (result.done) {
+      return value + decoder.decode();
+    }
+    value += decoder.decode(result.value, { stream: true });
+  }
+}
+
+describe('injectRSCPayload', () => {
+  test('backpressures at the retained-tail limit and conserves the trailer', async () => {
+    let rscController!: ReadableStreamDefaultController<Uint8Array>;
+    const rscStream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        rscController = controller;
+      },
+    });
+    const transform = injectRSCPayload(rscStream);
+    const output = readStream(transform.readable);
+    const writer = transform.writable.getWriter();
+
+    const retainedWhitespace = ' '.repeat(
+      RSC_HTML_CLOSING_TAIL_LIMIT - '</body>'.length,
+    );
+    await writer.write(encoder.encode(`<body>x</body>${retainedWhitespace}`));
+
+    let overflowSettled = false;
+    const overflow = writer.write(encoder.encode(' ')).then(() => {
+      overflowSettled = true;
+    });
+    await new Promise(resolve => setTimeout(resolve, 20));
+    expect(overflowSettled).toBe(false);
+
+    rscController.enqueue(encoder.encode('payload'));
+    rscController.close();
+    await overflow;
+    await writer.write(encoder.encode('</html>'));
+    await writer.close();
+
+    const spaces = `${retainedWhitespace} `;
+    expect(await output).toBe(`<body>x${flight}</body>${spaces}</html>`);
+  });
+
+  test('does not let flight overtake any split of an ordinary html tag', async () => {
+    const tag = '<span class="ordinary">';
+
+    for (let split = 1; split < tag.length; split++) {
+      const rscStream = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.enqueue(encoder.encode('payload'));
+          controller.close();
+        },
+      });
+      const transform = injectRSCPayload(rscStream);
+      const output = readStream(transform.readable);
+      const writer = transform.writable.getWriter();
+
+      await writer.write(encoder.encode(`<body>x${tag.slice(0, split)}`));
+      await writer.write(
+        encoder.encode(`${tag.slice(split)}y</span></body></html>`),
+      );
+      await writer.close();
+
+      expect(await output, `split after ${tag.slice(0, split)}`).toBe(
+        `<body>x${tag}y</span>${flight}</body></html>`,
+      );
+    }
+  });
+
+  test('conserves multi-chunk html and orders every flight chunk before the trailer', async () => {
+    let rscController!: ReadableStreamDefaultController<Uint8Array>;
+    const rscStream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        rscController = controller;
+      },
+    });
+    const transform = injectRSCPayload(rscStream);
+    const output = readStream(transform.readable);
+    const writer = transform.writable.getWriter();
+    const unicode = encoder.encode('–');
+
+    await writer.write(encoder.encode('<html><body><main>first'));
+    await writer.write(unicode.slice(0, 1));
+    await writer.write(unicode.slice(1));
+    await writer.write(encoder.encode('middle</main></bo'));
+    await writer.write(encoder.encode('dy></ht'));
+    await writer.write(encoder.encode('ml>'));
+
+    rscController.enqueue(encoder.encode('first'));
+    rscController.enqueue(encoder.encode('second'));
+    rscController.close();
+    await writer.close();
+
+    expect(await output).toBe(
+      '<html><body><main>first–middle</main>' +
+        '<script>(self.__FLIGHT_DATA||=[]).push("first")</script>' +
+        '<script>(self.__FLIGHT_DATA||=[]).push("second")</script>' +
+        '</body></html>',
+    );
+  });
+
+  test('does not truncate or inject inside an over-limit ordinary tag', async () => {
+    const attribute = 'x'.repeat(RSC_HTML_CLOSING_TAIL_LIMIT);
+    const partialTag = `<div data-value="${attribute}"`;
+    const rscStream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(encoder.encode('payload'));
+        controller.close();
+      },
+    });
+    const transform = injectRSCPayload(rscStream);
+    const output = readStream(transform.readable);
+    const writer = transform.writable.getWriter();
+
+    await writer.write(encoder.encode(`<body>x${partialTag}`));
+    await writer.write(encoder.encode('>y</div></body></html>'));
+    await writer.close();
+
+    expect(await output).toBe(
+      `<body>x${flight}${partialTag}>y</div></body></html>`,
+    );
+  });
+
+  test('propagates flight errors without publishing a synthetic trailer', async () => {
+    let rscController!: ReadableStreamDefaultController<Uint8Array>;
+    const failure = new Error('flight failed');
+    const rscStream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        rscController = controller;
+      },
+    });
+    const transform = injectRSCPayload(rscStream);
+    const output = readStream(transform.readable);
+    const writer = transform.writable.getWriter();
+
+    await writer.write(encoder.encode('<body>html</body></html>'));
+    rscController.error(failure);
+
+    await expect(Promise.all([writer.close(), output])).rejects.toBe(failure);
+  });
+});

package/tests/safeFailure.test.ts

@@ -0,0 +1,154 @@
+import {
+  createSafeFailureHttpResult,
+  createSafeFailureResponse,
+  createSafeJsonFailureResponse,
+  getSafeFailureStatus,
+} from '../src/safeFailure';
+
+const readBody = async (response: Response) =>
+  (await response.json()) as Record<string, unknown>;
+
+describe('safe failure responses', () => {
+  it.each([
+    [404, 'REQUEST_FAILED', 'Request failed'],
+    [500, 'INTERNAL_SERVER_ERROR', 'Internal Server Error'],
+    [503, 'SERVICE_UNAVAILABLE', 'Service Unavailable'],
+  ])('redacts a %i failure through every response surface', async (status, code, message) => {
+    const error = Object.assign(new Error('database-password'), {
+      status,
+      code: 'SECRET_CODE',
+      cause: 'root-cause',
+      details: 'internal-details',
+      stack: 'hidden-stack',
+    });
+    const expectedBody = {
+      success: false,
+      error: { code, message, status },
+    };
+
+    expect(createSafeFailureHttpResult(error)).toMatchObject({
+      status,
+      body: expectedBody,
+    });
+    for (const createResponse of [
+      createSafeFailureResponse,
+      createSafeJsonFailureResponse,
+    ]) {
+      const response = createResponse(error);
+      expect(response.status).toBe(status);
+      expect(response.headers.get('content-type')).toBe(
+        'application/json; charset=utf-8',
+      );
+      const body = await readBody(response);
+      expect(body).toEqual(expectedBody);
+      expect(JSON.stringify(body)).not.toMatch(
+        /database-password|SECRET_CODE|root-cause|internal-details|hidden-stack/u,
+      );
+    }
+
+    // Response construction must not destroy the raw error retained for
+    // internal structured diagnostics.
+    expect(error.cause).toBe('root-cause');
+    expect(error.details).toBe('internal-details');
+  });
+
+  it.each([
+    ['delay seconds text', ' 120 ', '120'],
+    ['leading-zero delay text', '000120', '120'],
+    ['delay seconds number', 2.1, '3'],
+    [
+      'largest safe delay number',
+      Number.MAX_SAFE_INTEGER,
+      String(Number.MAX_SAFE_INTEGER),
+    ],
+    [
+      'largest safe delay text',
+      String(Number.MAX_SAFE_INTEGER),
+      String(Number.MAX_SAFE_INTEGER),
+    ],
+    [
+      'canonical HTTP-date text',
+      'Sun, 30 Aug 2026 20:00:00 GMT',
+      'Sun, 30 Aug 2026 20:00:00 GMT',
+    ],
+    [
+      'valid Date object',
+      new Date(Date.UTC(2026, 7, 30, 20, 0, 0)),
+      'Sun, 30 Aug 2026 20:00:00 GMT',
+    ],
+  ])('canonicalizes %s for Retry-After', (_, retryAfter, expected) => {
+    const result = createSafeFailureHttpResult({ status: 503, retryAfter });
+    expect(result.headers['Retry-After']).toBe(expected);
+  });
+
+  it('converts Retry-After milliseconds to canonical delay seconds', () => {
+    expect(
+      createSafeFailureHttpResult({ status: 503, retryAfterMs: 2500 }).headers[
+        'Retry-After'
+      ],
+    ).toBe('3');
+  });
+
+  it.each([
+    ['a header injection payload', '120\r\nX-Injected: true'],
+    ['arbitrary text', 'after maintenance'],
+    ['an exponent string', '1e3'],
+    ['a decimal string', '2.1'],
+    ['a negative string', '-1'],
+    ['an unsafe integer string', '9007199254740992'],
+    ['an unsafe number', 1e21],
+    ['infinity', Number.POSITIVE_INFINITY],
+    ['a noncanonical date', 'Sunday, 30-Aug-26 20:00:00 GMT'],
+    ['an invalid date string', 'Wed, 99 Jun 2026 25:61:61 GMT'],
+    ['an invalid Date object', new Date(Number.NaN)],
+  ])('rejects %s as Retry-After', (_, retryAfter) => {
+    const result = createSafeFailureHttpResult({ status: 503, retryAfter });
+    expect(result.headers['Retry-After']).toBeUndefined();
+    expect(() =>
+      createSafeFailureResponse({ status: 503, retryAfter }),
+    ).not.toThrow();
+  });
+
+  it('never emits Retry-After for a non-503 response', () => {
+    expect(
+      createSafeFailureHttpResult({ status: 500, retryAfter: '120' }).headers[
+        'Retry-After'
+      ],
+    ).toBeUndefined();
+  });
+
+  it('fails closed without throwing when error property access is hostile', () => {
+    const hostile = new Proxy(
+      {},
+      {
+        has() {
+          throw new Error('proxy trap secret');
+        },
+        get() {
+          throw new Error('getter secret');
+        },
+      },
+    );
+
+    expect(getSafeFailureStatus(hostile)).toBe(500);
+    expect(createSafeFailureHttpResult(hostile)).toEqual({
+      status: 500,
+      body: {
+        success: false,
+        error: {
+          code: 'INTERNAL_SERVER_ERROR',
+          message: 'Internal Server Error',
+          status: 500,
+        },
+      },
+      headers: {
+        'content-type': 'application/json; charset=utf-8',
+      },
+    });
+  });
+
+  it('uses statusCode only when it is a valid failure status', () => {
+    expect(getSafeFailureStatus({ status: 200, statusCode: 503 })).toBe(503);
+    expect(getSafeFailureStatus({ status: 503.5, statusCode: 799 })).toBe(500);
+  });
+});

package/tests/shellStream.test.ts

@@ -0,0 +1,85 @@
+import {
+  beginHeadRender,
+  collectHeadRecord,
+  completeHeadRender,
+  createConservingWebShellStream,
+} from '../src';
+
+const MARKER = '<!--<?- SHELL_STREAM_END ?>-->';
+const encoder = new TextEncoder();
+const headMarker = (props: Record<string, string>) =>
+  `<template data-modern-helmet="${props['data-modern-helmet']}"></template>`;
+
+const streamFromChunks = (chunks: Uint8Array[]) =>
+  new ReadableStream<Uint8Array>({
+    start(controller) {
+      for (const chunk of chunks) {
+        controller.enqueue(chunk);
+      }
+      controller.close();
+    },
+  });
+
+const splitAt = (value: Uint8Array, offsets: number[]) => {
+  const chunks: Uint8Array[] = [];
+  let cursor = 0;
+  for (const offset of offsets) {
+    chunks.push(value.slice(cursor, offset));
+    cursor = offset;
+  }
+  chunks.push(value.slice(cursor));
+  return chunks;
+};
+
+describe('conserving web shell stream', () => {
+  it('preserves a large multichunk shell and tail across UTF-8 splits', async () => {
+    const shell = `α${'s'.repeat(9 * 1024)}`;
+    const tail = `尾${'t'.repeat(9 * 1024)}🌐done`;
+    const html = `${shell}${MARKER}${tail}`;
+    const bytes = encoder.encode(html);
+    const markerStart = encoder.encode(shell).length;
+    const markerEnd = markerStart + encoder.encode(MARKER).length;
+    const chunks = splitAt(bytes, [
+      1,
+      8192,
+      markerStart + 7,
+      markerEnd - 3,
+      markerEnd + 1,
+      bytes.length - 2,
+    ]);
+
+    const output = await new Response(
+      createConservingWebShellStream(streamFromChunks(chunks), {}, MARKER),
+    ).text();
+
+    expect(output).toBe(html);
+  });
+
+  it('reports once and errors when the source closes without a marker', async () => {
+    const onMissingMarker = rstest.fn();
+    const context = {};
+    let published: string[] = [];
+    const publish = (records: string[]) => {
+      published = records;
+    };
+    beginHeadRender(context);
+    const previous = collectHeadRecord(context, () => 'previous', publish)!;
+    completeHeadRender(context, headMarker(previous));
+    beginHeadRender(context);
+    collectHeadRecord(context, () => 'incomplete', publish);
+    const bytes = encoder.encode(`α${'x'.repeat(9 * 1024)}尾`);
+    const stream = createConservingWebShellStream(
+      streamFromChunks(splitAt(bytes, [1, 8192, bytes.length - 1])),
+      context,
+      MARKER,
+      onMissingMarker,
+    );
+
+    await expect(new Response(stream).text()).rejects.toThrow(
+      'React SSR stream ended before the shell marker',
+    );
+    expect(onMissingMarker).toHaveBeenCalledTimes(1);
+    expect(onMissingMarker).toHaveBeenCalledWith(expect.any(Error));
+    expect(published).toEqual(['previous']);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@modern-js/tsconfig/base",
+  "compilerOptions": {
+    "declaration": false,
+    "isolatedModules": true,
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}