@rangojs/router 0.5.1 → 0.6.0

package/src/rsc/server-action.ts

@@ -29,11 +29,22 @@ import {
   createSimpleRedirectResponse,
   interceptRedirectForPartial,
   attachLocationStateIfPresent,
+  matchAndRecordParams,
 } from "./helpers.js";
-import { renderRscResponse } from "./render-pipeline.js";
+import {
+  createRenderStageTraceBridge,
+  renderRscResponse,
+} from "./render-pipeline.js";
+import {
+  createRoutineTrace,
+  runRoutine,
+  step,
+  type RoutinePlan,
+} from "./routine-plan.js";
 import { warnNonRedirectActionResponse } from "./runtime-warnings.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { MatchResult } from "../types.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
 /**
  * Data flowing from action execution to the revalidation phase.
@@ -350,6 +361,17 @@ export function revalidateAfterAction<TEnv>(
   );
 }
 
+interface ActionRevalidationInput<TEnv> {
+  ctx: HandlerContext<TEnv>;
+  request: Request;
+  env: TEnv;
+  url: URL;
+  handleStore: ReturnType<typeof getRequestContext>["_handleStore"];
+  continuation: ActionContinuation;
+  renderSpan: TraceSpan;
+  reqCtx: ReturnType<typeof getRequestContext>;
+}
+
 async function revalidateAfterActionInner<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
@@ -359,14 +381,8 @@ async function revalidateAfterActionInner<TEnv>(
   continuation: ActionContinuation,
   renderSpan: TraceSpan,
 ): Promise<Response> {
-  const {
-    returnValue,
-    actionStatus,
-    temporaryReferences,
-    actionContext,
-    errorBoundary,
-  } = continuation;
   const reqCtx = getRequestContext();
+  const { actionContext } = continuation;
   // Expose the action that triggered this revalidation to the transition({ when })
   // gate (covers both the error-boundary and success gate calls below). Mirrors
   // the action fields a revalidate() predicate sees.
@@ -381,76 +397,63 @@ async function revalidateAfterActionInner<TEnv>(
   // in the background. See registerCachedFunction in cache/cache-runtime.ts.
   reqCtx._inActionRevalidation = true;
 
+  const trace = INTERNAL_RANGO_DEBUG
+    ? createRoutineTrace("action-revalidation")
+    : undefined;
+  const input: ActionRevalidationInput<TEnv> = {
+    ctx,
+    request,
+    env,
+    url,
+    handleStore,
+    continuation,
+    renderSpan,
+    reqCtx,
+  };
+  try {
+    return await runRoutine(actionRevalidationPlan(input), {
+      trace,
+      owner: reqCtx,
+    });
+  } finally {
+    if (trace) {
+      console.log(
+        `[routine] ${request.method} ${url.pathname} (${trace.name})\n${trace.format()}`,
+      );
+    }
+  }
+}
+
+/**
+ * The action-revalidation plan: render the deferred error boundary if the
+ * action threw and one matched, otherwise match affected segments (falling
+ * back to a full match for redirects) and render the partial payload.
+ */
+function* actionRevalidationPlan<TEnv>(
+  input: ActionRevalidationInput<TEnv>,
+): RoutinePlan<Response> {
+  const { ctx, request, env, url, continuation } = input;
+  const { actionContext, errorBoundary } = continuation;
+
   // Action threw and a boundary matched: render the (already-matched) error
   // boundary here so it runs inside the route-middleware wrapper, exactly like
-  // the success branch below. setRequestContextParams + the payload mirror the
-  // pre-deferral render that executeServerAction used to do inline.
+  // the success branch below.
   if (errorBoundary) {
-    setRequestContextParams(errorBoundary.params, errorBoundary.routeName);
-
-    const errorPayload: RscPayload = {
-      metadata: {
-        pathname: url.pathname,
-        // routerId exposed for the frontend (current app identity); see
-        // rsc-rendering.ts partial branch.
-        routerId: ctx.router.id,
-        segments: gateTransitions(
-          errorBoundary.segments,
-          reqCtx,
-          ctx.router.onError,
-        ),
-        isPartial: true,
-        matched: errorBoundary.matched,
-        diff: errorBoundary.diff,
-        resolvedIds: errorBoundary.resolvedIds,
-        params: errorBoundary.params,
-        isError: true,
-        handles: handleStore.stream(),
-        version: ctx.version,
-      },
-      returnValue,
-    };
-
-    // Intentionally omit attachLocationState for error payloads: location state
-    // is a success-only semantic. Error boundary responses update the error UI
-    // but should not mutate browser history state.
-
-    return renderRscResponse({
-      ctx,
-      request,
-      env,
-      url,
-      payload: errorPayload,
-      temporaryReferences,
-      init: {
-        status: actionStatus,
-        headers: {
-          "content-type": "text/x-component;charset=utf-8",
-          // Router identity for the client's pre-decode integrity check (the
-          // action apply path has no post-decode guard). See response-adapter.
-          "X-RSC-Router-Id": ctx.router.id,
-        },
-      },
-      tracking: {
-        mode: "action-revalidation",
-        routeKey: reqCtx._routeName,
-        actionId: actionContext?.actionId,
-        span: renderSpan,
-      },
-    });
+    return yield* step("render", () =>
+      renderActionBoundaryResponse(input, errorBoundary),
+    );
   }
 
-  const matchResult = await ctx.router.matchPartial(
-    request,
-    { env },
-    actionContext,
+  const matchResult = yield* step("match:partial", () =>
+    matchPartialAndRecord(ctx, request, env, actionContext),
   );
 
   if (!matchResult) {
     // matchPartial returns null when the route is a redirect or no previous-URL
     // context could be resolved. Check for redirect first.
-    const fullMatch = await ctx.router.match(request, { env });
-    setRequestContextParams(fullMatch.params, fullMatch.routeName);
+    const fullMatch = yield* step("match:fallback", () =>
+      matchAndRecordParams(ctx, request, env),
+    );
 
     if (fullMatch.redirect) {
       // Action context is always partial — use X-RSC-Redirect header so
@@ -476,8 +479,111 @@ async function revalidateAfterActionInner<TEnv>(
     );
   }
 
-  // Return updated segments
-  setRequestContextParams(matchResult.params, matchResult.routeName);
+  return yield* step("render", () =>
+    renderRevalidationResponse(input, matchResult),
+  );
+}
+
+/** matchPartial that stamps params/routeName when a result exists. */
+async function matchPartialAndRecord<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  actionContext: ActionContinuation["actionContext"],
+): Promise<
+  Awaited<ReturnType<HandlerContext<TEnv>["router"]["matchPartial"]>>
+> {
+  const matchResult = await ctx.router.matchPartial(
+    request,
+    { env },
+    actionContext,
+  );
+  if (matchResult) {
+    setRequestContextParams(matchResult.params, matchResult.routeName);
+  }
+  return matchResult;
+}
+
+/**
+ * Render the deferred action error boundary. setRequestContextParams + the
+ * payload mirror the pre-deferral render that executeServerAction used to do
+ * inline.
+ */
+function renderActionBoundaryResponse<TEnv>(
+  input: ActionRevalidationInput<TEnv>,
+  errorBoundary: MatchResult,
+): Promise<Response> {
+  const { ctx, request, env, url, handleStore, continuation, reqCtx } = input;
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
+
+  setRequestContextParams(errorBoundary.params, errorBoundary.routeName);
+
+  const errorPayload: RscPayload = {
+    metadata: {
+      pathname: url.pathname,
+      // routerId exposed for the frontend (current app identity); see
+      // rsc-rendering.ts partial branch.
+      routerId: ctx.router.id,
+      segments: gateTransitions(
+        errorBoundary.segments,
+        reqCtx,
+        ctx.router.onError,
+      ),
+      isPartial: true,
+      matched: errorBoundary.matched,
+      diff: errorBoundary.diff,
+      resolvedIds: errorBoundary.resolvedIds,
+      params: errorBoundary.params,
+      isError: true,
+      handles: handleStore.stream(),
+      version: ctx.version,
+    },
+    returnValue,
+  };
+
+  // Intentionally omit attachLocationState for error payloads: location state
+  // is a success-only semantic. Error boundary responses update the error UI
+  // but should not mutate browser history state.
+
+  return renderRscResponse({
+    ctx,
+    request,
+    env,
+    url,
+    payload: errorPayload,
+    temporaryReferences,
+    init: {
+      status: actionStatus,
+      headers: {
+        "content-type": "text/x-component;charset=utf-8",
+        // Router identity for the client's pre-decode integrity check (the
+        // action apply path has no post-decode guard). See response-adapter.
+        "X-RSC-Router-Id": ctx.router.id,
+      },
+    },
+    tracking: {
+      mode: "action-revalidation",
+      routeKey: input.reqCtx._routeName,
+      actionId: actionContext?.actionId,
+      span: input.renderSpan,
+      onEvent:
+        reqCtx._activeRoutine &&
+        createRenderStageTraceBridge(reqCtx._activeRoutine),
+    },
+  });
+}
+
+/** Render the updated segments after a successful action. */
+function renderRevalidationResponse<TEnv>(
+  input: ActionRevalidationInput<TEnv>,
+  matchResult: NonNullable<
+    Awaited<ReturnType<HandlerContext<TEnv>["router"]["matchPartial"]>>
+  >,
+): Promise<Response> {
+  const { ctx, request, env, url, handleStore, continuation, reqCtx } = input;
+  const { returnValue, actionStatus, temporaryReferences, actionContext } =
+    continuation;
 
   const payload: RscPayload = {
     metadata: {
@@ -524,7 +630,10 @@ async function revalidateAfterActionInner<TEnv>(
       mode: "action-revalidation",
       routeKey: reqCtx._routeName,
       actionId: actionContext?.actionId,
-      span: renderSpan,
+      span: input.renderSpan,
+      onEvent:
+        reqCtx._activeRoutine &&
+        createRenderStageTraceBridge(reqCtx._activeRoutine),
     },
   });
 }

package/src/rsc/shell-capture-constants.ts

@@ -25,3 +25,21 @@
  * docs/design/ppr-shell-resume.md (Cost model).
  */
 export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;
+
+/**
+ * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
+ * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
+ * captureShellHTML, AFTER the capture's router.match(); a handler wedged on a
+ * never-settling upstream await (autobarn pilot: a 30s+ tarpitting fetch)
+ * wedges the task with no deadline in force. The task's settle path releases
+ * the per-key stampede guard and the serialized capture-queue slot, so an
+ * unbounded task strands BOTH for the isolate's lifetime.
+ *
+ * 25s: above one full-budget attempt plus overhead (cutting a second attempt
+ * short is an acceptable loss — every terminal path backs the key off anyway),
+ * and below workerd's ~30s waitUntil grace so the cap timer still fires in a
+ * live context. When workerd kills the context BEFORE the cap fires, the timer
+ * dies with it — that stranding is healed by scheduleShellCapture's staleness
+ * check on the stampede guard, keyed off the same constant.
+ */
+export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;

package/src/rsc/shell-capture.ts

@@ -26,7 +26,10 @@ import {
   captureQueueDepths,
   enqueueSerializedCapture,
 } from "./capture-queue.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
+import {
+  SHELL_CAPTURE_MAX_WAIT_MS,
+  SHELL_CAPTURE_TASK_HARD_CAP_MS,
+} from "./shell-capture-constants.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import type { TraceSpan } from "../router/tracing.js";
@@ -185,15 +188,64 @@ function delay(ms: number): Promise<void> {
 }
 
 /**
- * Module-level in-flight key set: the stampede guard for background captures, and
+ * Bound one capture task at {@link SHELL_CAPTURE_TASK_HARD_CAP_MS}. Rejects on
+ * expiry so the caller's existing catch applies backoff + reporting and its
+ * settle path releases the stampede guard and queue slot; resolves/rejects
+ * transparently otherwise. The timer is unref'd so a pending cap never holds a
+ * Node dev process open.
+ */
+function raceTaskHardCap<T>(task: Promise<T>, key: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(
+        new Error(
+          `capture task for ${key} exceeded the ${SHELL_CAPTURE_TASK_HARD_CAP_MS}ms hard cap; ` +
+            `a handler is likely wedged on a never-settling await`,
+        ),
+      );
+    }, SHELL_CAPTURE_TASK_HARD_CAP_MS);
+    (timer as { unref?: () => void }).unref?.();
+    task.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error: unknown) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Module-level in-flight key map: the stampede guard for background captures, and
  * its single owner. One capture runs per key per isolate; concurrent MISS/stale
  * requests for the same key coalesce onto the first (the rest see the key present
  * in scheduleShellCapture and skip). Added when a capture is scheduled and cleared
- * in the task's finally once it settles, so a later request can recapture when TTL
- * rolls. Living here (not split across the middleware) keeps the add/clear
- * lifecycle in one layer.
+ * in the task's settle paths via a token-guarded release, so a later request can
+ * recapture when TTL rolls. Living here (not split across the middleware) keeps
+ * the add/clear lifecycle in one layer.
+ *
+ * The value is the owning task's token ({@link CaptureGuardToken}) rather than
+ * a bare set entry: workerd can kill a capture's waitUntil context before its
+ * finally runs (or the task can wedge past every deadline), stranding the key.
+ * scheduleShellCapture treats an entry older than
+ * SHELL_CAPTURE_TASK_HARD_CAP_MS as abandoned and reclaims it; the token guard
+ * keeps a late-settling stale task from releasing its replacement's entry.
  */
-const inFlightCaptures = new Set<string>();
+interface CaptureGuardToken {
+  startedAt: number;
+}
+
+const inFlightCaptures = new Map<string, CaptureGuardToken>();
+
+/** Token-guarded release: only the entry's owning task may clear it. */
+function releaseCaptureGuard(key: string, token: CaptureGuardToken): void {
+  if (inFlightCaptures.get(key) === token) {
+    inFlightCaptures.delete(key);
+  }
+}
 
 /**
  * Refused-capture backoff bounds. The window is EXPONENTIAL in the consecutive
@@ -855,6 +907,15 @@ export function gateFlightForCapture(
  */
 export interface ShellCaptureDescriptor {
   key: string;
+  /**
+   * The key's search portion (shellSearchSeed: `?`-prefixed sorted search,
+   * cache.searchParams filter applied, or ""). Seeds the capture render's SSR
+   * store so static-part `useSearchParams` reads bake markup consistent with
+   * the shell's own key; the resume pass derives the identical string from
+   * the HIT request. Computed next to the key so the two cannot drift.
+   * Omitted (build-time bare-pathname captures) = search-less, same as "".
+   */
+  searchSeed?: string;
   /**
    * The RSC handler's build version (HandlerContext.version), stamped into the
    * stored entry as ShellCacheEntry.buildVersion — the serve-side
@@ -918,9 +979,17 @@ export function scheduleShellCapture(
   descriptor: ShellCaptureDescriptor,
 ): void {
   const key = descriptor.key;
-  if (inFlightCaptures.has(key)) {
-    publishCaptureDebugEvent(descriptor, { key, outcome: "skip-in-flight" });
-    return;
+  const inFlight = inFlightCaptures.get(key);
+  if (inFlight) {
+    if (Date.now() - inFlight.startedAt <= SHELL_CAPTURE_TASK_HARD_CAP_MS) {
+      publishCaptureDebugEvent(descriptor, { key, outcome: "skip-in-flight" });
+      return;
+    }
+    // Older than the task hard cap: the owning task never settled (wedged
+    // render, or workerd killed its context before the release ran). Treat the
+    // key as abandoned and schedule a replacement — the set() below installs a
+    // new token, and the stale task's token-guarded release can no longer
+    // touch it.
   }
   // Refused/failed within the window → skip the doomed re-render (one probe per
   // key per window per isolate). Expired entries self-evict inside the check.
@@ -942,7 +1011,8 @@ export function scheduleShellCapture(
     publishCaptureDebugEvent(descriptor, { key, outcome: "skip-inert-store" });
     return;
   }
-  inFlightCaptures.add(key);
+  const guardToken: CaptureGuardToken = { startedAt: Date.now() };
+  inFlightCaptures.set(key, guardToken);
   const captureTask = async (span: TraceSpan) => {
     try {
       const setupUrl = descriptor.navigationOnly
@@ -962,14 +1032,24 @@ export function scheduleShellCapture(
       ) {
         return;
       }
-      const outcome = await runShellCapture(
-        ctx,
-        request,
-        env,
-        url,
-        reqCtx,
-        resolvedSsrModule,
-        descriptor,
+      // Hard-capped: SHELL_CAPTURE_MAX_WAIT_MS arms only inside
+      // captureShellHTML, AFTER the capture's router.match() — a handler
+      // wedged on a never-settling upstream await has no deadline in force
+      // and would strand the stampede guard and the queue slot (autobarn
+      // pilot). The cap rejects, riding the existing catch: backoff +
+      // reportCacheError + token-guarded release. The abandoned attempt keeps
+      // running until its context dies; nothing awaits it.
+      const outcome = await raceTaskHardCap(
+        runShellCapture(
+          ctx,
+          request,
+          env,
+          url,
+          reqCtx,
+          resolvedSsrModule,
+          descriptor,
+        ),
+        key,
       );
       span.setAttribute("rango.background.outcome", outcome);
       // Update the negative cache off the terminal outcome. A stored shell clears
@@ -998,7 +1078,7 @@ export function scheduleShellCapture(
       });
       reportCacheError(error, "cache-write", "[ShellCache] capture", reqCtx);
     } finally {
-      inFlightCaptures.delete(key);
+      releaseCaptureGuard(key, guardToken);
     }
   };
   // Serialize capture EXECUTION per isolate (capture-queue.ts): concurrent
@@ -1049,7 +1129,7 @@ export function scheduleShellCapture(
         );
       } catch (error) {
         if (error instanceof CaptureQueueFullError) {
-          inFlightCaptures.delete(key);
+          releaseCaptureGuard(key, guardToken);
           span.setAttribute("rango.background.outcome", "skip-capacity");
           publishCaptureDebugEvent(descriptor, {
             key,
@@ -1061,7 +1141,7 @@ export function scheduleShellCapture(
           // Dropped unrun after waiting past the queue budget: no backoff (the
           // route is not doomed, the isolate was busy) — a later request
           // re-probes the key.
-          inFlightCaptures.delete(key);
+          releaseCaptureGuard(key, guardToken);
           span.setAttribute("rango.background.outcome", "skip-queue-timeout");
           span.setAttribute(
             "rango.background.queue_wait_ms",
@@ -1682,6 +1762,9 @@ async function captureAndStoreShell(
         captureShellHTML(gate.stream, {
           quiesce,
           maxWaitMs: capture.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS,
+          // The shell key's own search seeds the capture render's store —
+          // static-part search reads bake what the key names.
+          search: capture.searchSeed,
         }),
       );
     } catch (error) {

package/src/rsc/shell-serve.ts

@@ -129,9 +129,22 @@ export function resolvePprConfig(
  * and lookup makes every shell request a permanent miss.
  */
 export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
+  return `${url.host}${url.pathname}${shellSearchSeed(url, filter)}:shell`;
+}
+
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string {
   const sorted = sortedSearchString(url.searchParams, filter);
-  const searchSuffix = sorted ? `?${sorted}` : "";
-  return `${url.host}${url.pathname}${searchSuffix}:shell`;
+  return sorted ? `?${sorted}` : "";
 }
 
 /**

package/src/rsc/ssr-setup.ts

@@ -111,7 +111,16 @@ export function createSsrHtmlStage<TEnv>(
     );
     return {
       render: () =>
-        ssrModule.renderHTML(flight.stream, { ...options.render, streamMode }),
+        // search: the LIVE request's query string, threaded out-of-band into
+        // the SSR pass so useSearchParams sees real values during document
+        // renders. Deliberately not payload metadata: cached/prerendered
+        // payloads replay captured metadata, and search is not route
+        // identity — it must always come from the request being served.
+        ssrModule.renderHTML(flight.stream, {
+          ...options.render,
+          streamMode,
+          search: options.url.search,
+        }),
       ...(options.init && { init: options.init }),
     };
   };

package/src/rsc/types.ts

@@ -35,10 +35,27 @@ export interface RscPayload {
     /** Merged route params from the matched route */
     params?: Record<string, string>;
     slots?: Record<string, SlotState>;
+    /**
+     * Intercept TARGET route names reachable from this location as a
+     * navigation origin (see MatchResult.interceptTargets). The browser-local
+     * clientUrls matcher declines optimistic presentation for these.
+     */
+    interceptTargets?: string[];
     /** Root layout component for browser-side re-renders (client component reference) */
     rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
     /** Handle data accumulated across route segments (async generator that yields on each push) */
     handles?: AsyncGenerator<HandleData, void, unknown>;
+    /**
+     * Document-lane late handle channel: full-state updates for pushes landing
+     * AFTER the handler barrier (streaming loader bodies writing handles
+     * mid-body). `handles` above is drained to completion in blocking
+     * positions (SSR seed, pre-hydration), so late pushes need this separate
+     * generator, consumed non-blocking post-hydration (rsc-router.tsx).
+     * Empty/instantly-complete when no auxiliary-lane work is pending at the
+     * handler barrier. Full payloads only — partial payloads' `handles`
+     * generator streams to full settle already.
+     */
+    handlesLate?: AsyncGenerator<HandleData, void, unknown>;
     /** RSC version string for cache invalidation */
     version?: string;
     /** Cloudflare dev worker generation used for stale-document convergence. */
@@ -158,6 +175,18 @@ export interface SSRRenderOptions {
    * - `"allReady"` — await `stream.allReady` before returning.
    */
   streamMode?: import("../router/router-options.js").SSRStreamMode;
+
+  /**
+   * The live request's query string (`url.search`, `?`-prefixed or empty).
+   * Seeds the SSR navigation store so `useSearchParams` (and
+   * `useNavigation().location`) carry real values during document renders.
+   * Out-of-band by design — never payload metadata, which cached/prerendered
+   * payloads replay; search is not route identity. The build-time prerender
+   * pass passes none — build shells capture bare pathnames and serve
+   * search-less requests only (runtime ppr captures seed the shell key's
+   * search; see ShellCaptureOptions.search in the SSR entry).
+   */
+  search?: string;
 }
 
 /**
@@ -179,7 +208,7 @@ export interface SSRModule {
    */
   captureShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { quiesce: Promise<void>; maxWaitMs?: number },
+    options: { quiesce: Promise<void>; maxWaitMs?: number; search?: string },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 
   /**
@@ -192,7 +221,7 @@ export interface SSRModule {
    */
   resumeShellHTML?: (
     rscStream: ReadableStream<Uint8Array>,
-    options: { postponed: string | null; nonce?: string },
+    options: { postponed: string | null; nonce?: string; search?: string },
   ) => Promise<ReadableStream<Uint8Array>>;
 }