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

package/src/server/worker.ts

@@ -0,0 +1,94 @@
+import { collectDocumentAssets, type DocumentAsset } from '../document';
+import { assertRendererIdentity, type RendererIdentity } from '../identity';
+import { dispatchNativeRequest, rejectNativeRscRequest } from './dispatch';
+import type {
+  NativeExecutionContext,
+  NativeServerConfig,
+  NativeServerManifest,
+} from './types';
+
+/** Build-validated per-entry inputs a worker bundle cannot read from disk. */
+export interface NativeWorkerEntryResources {
+  readonly assets: readonly DocumentAsset[];
+  /** Opaque compiler-owned JSON, revalidated by the native request handler. */
+  readonly nativeManifest?: unknown;
+  readonly hydrationBuildId?: string;
+  readonly serverConfig: NativeServerConfig;
+  /** Present only when the entry admits a CSR fallback request. */
+  readonly csrFallbackHeader?: string;
+  readonly nonce?: string;
+}
+
+export interface NativeWorkerDispatchOptions<Bindings extends object> {
+  readonly identity: RendererIdentity;
+  /** The imported worker bundle: its namespace or default-exported manifest. */
+  readonly bundle: unknown;
+  readonly resources: NativeWorkerEntryResources;
+  /** The module worker `env`, forwarded unchanged as the platform binding. */
+  readonly bindings: Bindings | undefined;
+  readonly executionContext?: NativeExecutionContext;
+}
+
+function workerManifest<Bindings extends object>(
+  bundle: unknown,
+  identity: RendererIdentity,
+): NativeServerManifest<Bindings> {
+  const candidate =
+    bundle &&
+    typeof bundle === 'object' &&
+    !('rendererIdentity' in bundle) &&
+    'default' in bundle
+      ? bundle.default
+      : bundle;
+  if (
+    !candidate ||
+    (typeof candidate !== 'object' && typeof candidate !== 'function') ||
+    !('rendererIdentity' in candidate) ||
+    !('nativeRequestHandler' in candidate) ||
+    typeof candidate.nativeRequestHandler !== 'function'
+  ) {
+    throw new Error(
+      'Native worker bundle requires its renderer identity and request handler.',
+    );
+  }
+  assertRendererIdentity(
+    candidate.rendererIdentity as RendererIdentity,
+    identity,
+  );
+  return candidate as NativeServerManifest<Bindings>;
+}
+
+/** Worker Fetch dispatch over the same native handler the Node host loads. */
+export function dispatchNativeWorkerRequest<Bindings extends object>(
+  request: Request,
+  options: NativeWorkerDispatchOptions<Bindings>,
+): Promise<Response> {
+  const rejection = rejectNativeRscRequest(request);
+  if (rejection) return Promise.resolve(rejection);
+  const { resources } = options;
+  const query = new URL(request.url).searchParams;
+  const forceCSR = Boolean(
+    resources.csrFallbackHeader &&
+      (query.get('csr') || request.headers.get(resources.csrFallbackHeader)),
+  );
+  const bindings = (
+    options.bindings !== null && typeof options.bindings === 'object'
+      ? options.bindings
+      : {}
+  ) as Bindings;
+  return dispatchNativeRequest<Bindings>(request, {
+    identity: options.identity,
+    platform: 'worker',
+    executionContext: options.executionContext,
+    hydrationBuildId: resources.hydrationBuildId,
+    loadManifest: () =>
+      workerManifest<Bindings>(options.bundle, options.identity),
+    context: {
+      assets: collectDocumentAssets(resources.assets),
+      nativeManifest: resources.nativeManifest,
+      bindings,
+      serverConfig: { ...resources.serverConfig, forceCSR },
+      nonce: resources.nonce,
+    },
+  });
+}

package/src/session/cache.ts

@@ -0,0 +1,177 @@
+import { identityCacheKey, type RendererIdentity } from '../identity';
+import type {
+  DocumentCachePolicy,
+  ResponseHeaders,
+  ResponsePolicy,
+} from './types';
+
+type CacheMode = DocumentCachePolicy['mode'];
+
+/** Compute this before looking up any application-provided request key. */
+export function documentCacheKey(
+  identity: RendererIdentity,
+  requestKey: string,
+): string {
+  if (typeof requestKey !== 'string' || requestKey.length === 0) {
+    throw new TypeError('A document cache request key must be nonempty.');
+  }
+  return JSON.stringify([identityCacheKey(identity), requestKey]);
+}
+
+/** Header fields with each Set-Cookie kept as its own entry. */
+export function responseHeaders(headers: Headers): [string, string][] {
+  const fields: [string, string][] = [];
+  headers.forEach((value, name) => {
+    if (name !== 'set-cookie') fields.push([name, value]);
+  });
+  for (const cookie of headers.getSetCookie()) {
+    fields.push(['set-cookie', cookie]);
+  }
+  return fields;
+}
+
+export function policyHeaders(headers: ResponseHeaders): Headers {
+  const result = new Headers();
+  for (const [name, value] of headers) result.append(name, value);
+  return result;
+}
+
+const NO_STORE = { mode: 'no-store' as const, ages: [] };
+
+const CACHE_DIRECTIVE =
+  /\s*([!#$%&'*+.^_`|~\w-]+)\s*(?:=\s*([!#$%&'*+.^_`|~\w-]+|"(?:[^"\\]|\\.)*"))?\s*(?:,|$)/uy;
+
+/**
+ * Every Cache-Control directive in order, names lowercased, or `undefined`
+ * when any part is malformed (an unterminated quote, trailing syntax). Quoted
+ * values are consumed whole, so their text is never read as a directive.
+ */
+export function parseCacheControl(
+  value: string,
+): { name: string; value: string | undefined }[] | undefined {
+  const directives: { name: string; value: string | undefined }[] = [];
+  let index = 0;
+  while (index < value.length) {
+    CACHE_DIRECTIVE.lastIndex = index;
+    const match = CACHE_DIRECTIVE.exec(value);
+    if (!match || CACHE_DIRECTIVE.lastIndex === index) return undefined;
+    directives.push({ name: match[1].toLowerCase(), value: match[2] });
+    index = CACHE_DIRECTIVE.lastIndex;
+  }
+  return directives;
+}
+
+/** Read Cache-Control. Malformed or repeated lifetimes never cache. */
+function cacheDirectives(value: string | null): {
+  mode: CacheMode;
+  ages: number[];
+} {
+  let mode: CacheMode = 'public';
+  const ages: number[] = [];
+  const ageNames = new Set<string>();
+  const parsed = parseCacheControl(value ?? '');
+  if (!parsed) return NO_STORE;
+  for (const { name, value: raw } of parsed) {
+    if (name === 'no-store' || name === 'no-cache') mode = 'no-store';
+    else if (name === 'private' && mode !== 'no-store') mode = 'private';
+    if (name === 'max-age' || name === 's-maxage') {
+      const age = Number(raw);
+      if (
+        ageNames.has(name) ||
+        !/^\d+$/u.test(raw ?? '') ||
+        !Number.isSafeInteger(age)
+      ) {
+        return NO_STORE;
+      }
+      ageNames.add(name);
+      ages.push(age);
+    }
+  }
+  return { mode, ages };
+}
+
+/** The `max-age` and `s-maxage` lifetimes these headers declare. */
+export function headerMaxAgeSeconds(headers: Headers): number[] {
+  return cacheDirectives(headers.get('cache-control')).ages;
+}
+
+/** The most shareable mode these headers allow; lifetimes go into `ages`. */
+function headerCacheMode(headers: Headers, ages: number[]): CacheMode {
+  const control = cacheDirectives(headers.get('cache-control'));
+  ages.push(...control.ages);
+  if (
+    headers.has('set-cookie') ||
+    headers
+      .get('vary')
+      ?.split(',')
+      .some(value => value.trim() === '*')
+  ) {
+    return 'no-store';
+  }
+  return control.mode;
+}
+
+function isSingleHtmlContentType(headers: Headers): boolean {
+  const type = headers.get('content-type');
+  return (
+    !type?.includes(',') &&
+    type?.split(';')[0].trim().toLowerCase() === 'text/html'
+  );
+}
+
+export function permitsDocumentCache(policy: ResponsePolicy): boolean {
+  if (
+    policy.kind !== 'document' ||
+    policy.status !== 200 ||
+    policy.cache.mode !== 'public'
+  ) {
+    return false;
+  }
+  const headers = policyHeaders(policy.headers);
+  return (
+    headerCacheMode(headers, []) === 'public' &&
+    isSingleHtmlContentType(headers)
+  );
+}
+
+/**
+ * Narrow a policy's cache to what every header source allows, then write the
+ * matching Cache-Control to `outgoing`. Only a 200 HTML document can be public;
+ * its lifetime is the shortest one any source declares.
+ */
+export function restrictDocumentCache(
+  policy: ResponsePolicy,
+  sources: readonly Headers[],
+  outgoing: Headers,
+): DocumentCachePolicy {
+  const original = policyHeaders(policy.headers);
+  let mode: CacheMode = policy.cache.mode;
+  const ages =
+    policy.cache.mode === 'public' ? [policy.cache.maxAgeSeconds] : [];
+  for (const headers of [original, ...sources, outgoing]) {
+    const restricted = headerCacheMode(headers, ages);
+    if (restricted === 'no-store') mode = 'no-store';
+    else if (restricted === 'private' && mode === 'public') mode = 'private';
+  }
+  if (
+    policy.kind !== 'document' ||
+    policy.status !== 200 ||
+    !isSingleHtmlContentType(original) ||
+    !isSingleHtmlContentType(outgoing)
+  ) {
+    mode = 'no-store';
+  }
+  if (mode === 'public') {
+    const maxAgeSeconds = Math.min(...ages);
+    outgoing.set(
+      'cache-control',
+      `public, max-age=${maxAgeSeconds}, s-maxage=${maxAgeSeconds}, must-revalidate`,
+    );
+    return { mode, maxAgeSeconds };
+  }
+  outgoing.set(
+    'cache-control',
+    mode === 'private' ? 'private, max-age=0, must-revalidate' : 'no-store',
+  );
+  return { mode };
+}

package/src/session/index.ts

@@ -0,0 +1,11 @@
+export { untilAborted } from '../abort';
+export {
+  documentCacheKey,
+  headerMaxAgeSeconds,
+  permitsDocumentCache,
+  policyHeaders,
+  responseHeaders,
+  restrictDocumentCache,
+} from './cache';
+export { createRequestSession } from './request';
+export type * from './types';

package/src/session/request.ts

@@ -0,0 +1,324 @@
+import type { RendererIdentity } from '../identity';
+import { identityCacheKey } from '../identity';
+import { permitsDocumentCache, policyHeaders } from './cache';
+import type {
+  RequestCleanup,
+  RequestCompletion,
+  RequestPlatform,
+  RequestSession,
+  RequestState,
+  ResponsePolicy,
+} from './types';
+
+function freezeResponsePolicy(policy: ResponsePolicy): ResponsePolicy {
+  if (
+    !Number.isInteger(policy.status) ||
+    policy.status < 200 ||
+    policy.status > 599
+  ) {
+    throw new TypeError(
+      'A renderer response status must be an integer from 200 to 599.',
+    );
+  }
+  if (policy.kind !== 'document' && policy.kind !== 'terminal') {
+    throw new TypeError(
+      'A renderer response must identify its document or terminal outcome.',
+    );
+  }
+  const statusText = policy.statusText;
+  if (statusText !== undefined && typeof statusText !== 'string') {
+    throw new TypeError('A renderer response status text must be a string.');
+  }
+  // Fetch validates the reason text before a response can claim its stream.
+  new Response(null, {
+    status: policy.status,
+    ...(statusText === undefined ? {} : { statusText }),
+  });
+  if (!['no-store', 'private', 'public'].includes(policy.cache.mode)) {
+    throw new TypeError('A renderer response has an unknown cache policy.');
+  }
+  if (
+    policy.cache.mode === 'public' &&
+    (!Number.isInteger(policy.cache.maxAgeSeconds) ||
+      policy.cache.maxAgeSeconds < 0)
+  ) {
+    throw new TypeError(
+      'A public document cache lifetime must be a nonnegative integer.',
+    );
+  }
+  const headers = policy.headers.map(([name, value]) => {
+    // Validate before committing. Keep separate Set-Cookie entries in the policy.
+    new Headers([[name, value]]);
+    return Object.freeze([name, value] as const);
+  });
+  return Object.freeze({
+    kind: policy.kind,
+    status: policy.status,
+    ...(statusText === undefined ? {} : { statusText }),
+    headers: Object.freeze(headers),
+    cache: Object.freeze({ ...policy.cache }),
+  });
+}
+
+/** Owns one request and the lifetime of its response body, not a server instance. */
+export function createRequestSession<Bindings extends object>(input: {
+  request: Request;
+  identity: RendererIdentity;
+  platform: RequestPlatform<Bindings>;
+}): RequestSession<Bindings> {
+  identityCacheKey(input.identity);
+  if (input.platform.kind !== 'node' && input.platform.kind !== 'worker') {
+    throw new TypeError(
+      'A renderer request requires an explicit Node or worker binding.',
+    );
+  }
+  const identity = Object.freeze({ ...input.identity });
+  const platform = Object.freeze({ ...input.platform });
+  const abortController = new AbortController();
+  const disposers = new Set<RequestCleanup>();
+  let state: RequestState = 'matching';
+  let policy: ResponsePolicy | undefined;
+  let committedPolicy: ResponsePolicy | undefined;
+  let fallback = false;
+  let responseCreated = false;
+  let hasDocumentBody = false;
+  let deliveredResponse: Response | undefined;
+  let deliveredHeaders: Headers | undefined;
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  let bodyController: ReadableStreamDefaultController<Uint8Array> | undefined;
+  let cancelPromise: Promise<void> | undefined;
+  let finishPromise: Promise<RequestCompletion> | undefined;
+  let resolveCompletion!: (completion: RequestCompletion) => void;
+  const completion = new Promise<RequestCompletion>(resolve => {
+    resolveCompletion = resolve;
+  });
+
+  const cancelSource = (reason: unknown) => {
+    cancelPromise ??= reader
+      ? reader.cancel(reason).finally(() => reader?.releaseLock())
+      : Promise.resolve();
+    return cancelPromise;
+  };
+
+  const finish = (
+    terminalState: RequestCompletion['state'],
+    error?: unknown,
+  ): Promise<RequestCompletion> => {
+    if (finishPromise) return finishPromise;
+    state = terminalState;
+    input.request.signal.removeEventListener('abort', onRequestAbort);
+    const ownedDisposers = [...disposers].reverse();
+    disposers.clear();
+    finishPromise = Promise.resolve().then(async () => {
+      const cleanupErrors: unknown[] = [];
+      let recorded = false;
+      // A native cancel operation can wait for its renderer owner to dispose,
+      // so both start together. Completion never waits on the source's cancel
+      // hook, which may not settle; an error it reports by then is recorded.
+      if (terminalState !== 'completed')
+        void cancelSource(error).catch(cancelError => {
+          if (!recorded) cleanupErrors.push(cancelError);
+        });
+      for (const dispose of ownedDisposers) {
+        try {
+          await dispose();
+        } catch (cleanupError) {
+          cleanupErrors.push(cleanupError);
+        }
+      }
+      // One turn lets an immediately rejected cancellation be recorded.
+      await Promise.resolve();
+      recorded = true;
+      if (terminalState === 'completed' && cleanupErrors.length > 0)
+        state = 'failed';
+      const result: RequestCompletion = Object.freeze({
+        state: state as RequestCompletion['state'],
+        fallback,
+        ...(error !== undefined ? { error } : {}),
+        cleanupErrors: Object.freeze(cleanupErrors),
+        cacheEligible:
+          state === 'completed' &&
+          hasDocumentBody &&
+          !fallback &&
+          committedPolicy !== undefined &&
+          permitsDocumentCache({
+            ...committedPolicy,
+            // Server middleware can append cookies to the Fetch Response before
+            // transport sends it. Cache admission must inspect those final headers.
+            headers: deliveredHeaders
+              ? [...deliveredHeaders.entries()]
+              : committedPolicy.headers,
+          }),
+      });
+      resolveCompletion(result);
+      return result;
+    });
+    if (terminalState !== 'completed') {
+      // Publish terminal ownership before notifying native abort listeners.
+      // Re-entrant failures and cancellations then share this same completion.
+      abortController.abort(error);
+      bodyController?.error(error);
+    }
+    return finishPromise;
+  };
+
+  const abort = (
+    reason: unknown = new DOMException(
+      'The renderer request was aborted.',
+      'AbortError',
+    ),
+  ) => {
+    void finish('aborted', reason);
+  };
+
+  function onRequestAbort() {
+    void abort(input.request.signal.reason);
+  }
+
+  const session: RequestSession<Bindings> = {
+    request: input.request,
+    identity,
+    platform,
+    signal: abortController.signal,
+    get state() {
+      return state;
+    },
+    get responsePolicy() {
+      return policy;
+    },
+    get committedPolicy() {
+      return committedPolicy;
+    },
+    completion,
+    resolveResponse(nextPolicy) {
+      if (committedPolicy || finishPromise) {
+        throw new Error(
+          'Renderer response status and headers are already committed or terminated.',
+        );
+      }
+      policy = freezeResponsePolicy(nextPolicy);
+      if (state === 'matching') state = 'ready';
+    },
+    startRendering() {
+      if (state !== 'ready') {
+        throw new Error(
+          'Resolve the blocking HTTP outcome before starting the renderer.',
+        );
+      }
+      state = 'rendering';
+    },
+    registerCleanup(dispose) {
+      if (finishPromise)
+        throw new Error(
+          'Cannot register cleanup after a renderer request terminates.',
+        );
+      disposers.add(dispose);
+      return () => {
+        disposers.delete(dispose);
+      };
+    },
+    markFallback() {
+      if (finishPromise)
+        throw new Error(
+          'Cannot change fallback disposition after a renderer request terminates.',
+        );
+      fallback = true;
+    },
+    respond(body) {
+      if (responseCreated || committedPolicy || finishPromise) {
+        throw new Error(
+          'A renderer request has exactly one response body consumer.',
+        );
+      }
+      if (!policy || (state !== 'ready' && state !== 'rendering')) {
+        throw new Error(
+          'Resolve the blocking HTTP outcome before committing a response.',
+        );
+      }
+      if (body !== null && [204, 205, 304].includes(policy.status)) {
+        throw new TypeError(
+          `HTTP ${policy.status} cannot contain a renderer response body.`,
+        );
+      }
+      reader = body?.getReader();
+      hasDocumentBody = body !== null;
+      responseCreated = true;
+      committedPolicy = policy;
+      state = 'committed';
+      const headers = policyHeaders(committedPolicy.headers);
+      let wrappedBody: ReadableStream<Uint8Array> | null = null;
+      if (!reader) {
+        void finish('completed');
+      } else {
+        const sourceReader = reader;
+        wrappedBody = new ReadableStream<Uint8Array>(
+          {
+            start(controller) {
+              bodyController = controller;
+            },
+            async pull(controller) {
+              try {
+                const next = await sourceReader.read();
+                if (finishPromise) return;
+                if (!next.done) {
+                  controller.enqueue(next.value);
+                  return;
+                }
+                sourceReader.releaseLock();
+                const result = await finish('completed');
+                if (result.cleanupErrors.length > 0) {
+                  controller.error(
+                    new AggregateError(
+                      result.cleanupErrors,
+                      'Renderer request cleanup failed.',
+                    ),
+                  );
+                } else {
+                  controller.close();
+                }
+              } catch (error) {
+                if (!finishPromise) {
+                  await finish('failed', error);
+                  controller.error(error);
+                }
+              }
+            },
+            cancel(reason) {
+              abort(reason);
+              return completion.then(() => {});
+            },
+          },
+          { highWaterMark: 0 },
+        );
+      }
+      const response = new Response(wrappedBody, {
+        status: committedPolicy.status,
+        ...(committedPolicy.statusText === undefined
+          ? {}
+          : { statusText: committedPolicy.statusText }),
+        headers,
+      });
+      deliveredResponse = response;
+      deliveredHeaders = response.headers;
+      return response;
+    },
+    ownsResponseBody(response) {
+      return (
+        deliveredResponse !== undefined &&
+        (response === deliveredResponse ||
+          (deliveredResponse.body !== null &&
+            response.body === deliveredResponse.body))
+      );
+    },
+    fail(error) {
+      void finish('failed', error);
+    },
+    abort,
+  };
+  if (input.request.signal.aborted) onRequestAbort();
+  else
+    input.request.signal.addEventListener('abort', onRequestAbort, {
+      once: true,
+    });
+  return session;
+}

package/src/session/types.ts

@@ -0,0 +1,60 @@
+import type { RendererIdentity } from '../identity';
+
+export type ResponseHeaders = ReadonlyArray<readonly [string, string]>;
+
+export type DocumentCachePolicy =
+  | { readonly mode: 'no-store' | 'private' }
+  | { readonly mode: 'public'; readonly maxAgeSeconds: number };
+
+export interface ResponsePolicy {
+  readonly kind: 'document' | 'terminal';
+  readonly status: number;
+  readonly statusText?: string;
+  readonly headers: ResponseHeaders;
+  readonly cache: DocumentCachePolicy;
+}
+
+export interface RequestPlatform<Bindings extends object = object> {
+  readonly kind: 'node' | 'worker';
+  readonly bindings: Bindings;
+}
+
+export type RequestState =
+  | 'matching'
+  | 'ready'
+  | 'rendering'
+  | 'committed'
+  | 'completed'
+  | 'failed'
+  | 'aborted';
+
+export interface RequestCompletion {
+  readonly state: 'completed' | 'failed' | 'aborted';
+  readonly fallback: boolean;
+  readonly error?: unknown;
+  readonly cleanupErrors: readonly unknown[];
+  readonly cacheEligible: boolean;
+}
+
+export type RequestCleanup = () => void | Promise<void>;
+
+export interface RequestSession<Bindings extends object = object> {
+  readonly request: Request;
+  readonly identity: Readonly<RendererIdentity>;
+  readonly platform: RequestPlatform<Bindings>;
+  readonly signal: AbortSignal;
+  readonly state: RequestState;
+  readonly responsePolicy: ResponsePolicy | undefined;
+  readonly committedPolicy: ResponsePolicy | undefined;
+  readonly completion: Promise<RequestCompletion>;
+  resolveResponse(policy: ResponsePolicy): void;
+  startRendering(): void;
+  registerCleanup(cleanup: RequestCleanup): () => void;
+  markFallback(): void;
+  respond(body: ReadableStream<Uint8Array> | null): Response;
+  /** The returned response must deliver this session's final owned stream. */
+  ownsResponseBody(response: Response): boolean;
+  /** Notify termination. Await completion separately outside owned cleanup. */
+  fail(error: unknown): void;
+  abort(reason?: unknown): void;
+}