@reckona/mreact-router 0.0.188 → 0.0.190

package/src/adapters/aws-lambda.ts

@@ -22,8 +22,41 @@ import {
 import type { AppRouterResponseHook } from "../render.js";
 import type { RouterInstrumentation } from "../trace.js";
 
-/** Re-exports router instrumentation hooks for AWS Lambda handlers. */
-export type { RouterInstrumentation } from "../trace.js";
+/** Re-exports cache contracts used by AWS Lambda handlers. */
+export type { AppRouterCache, AppRouterCacheEntry } from "../cache.js";
+/** Re-exports server action contracts used by AWS Lambda handlers. */
+export type {
+  AppRouterAllowedServerAction,
+  AppRouterServerActionOptions,
+} from "../actions.js";
+/** Re-exports logger contracts used by AWS Lambda handlers. */
+export type {
+  AppRouterCspInlineNonceWarningLogEvent,
+  AppRouterLogger,
+  AppRouterLogError,
+  AppRouterLogEvent,
+  AppRouterRenderTimingLogEvent,
+  AppRouterRequestEndLogEvent,
+  AppRouterRequestErrorLogEvent,
+  AppRouterRequestStartLogEvent,
+  AppRouterRequestTimingLogEvent,
+  AppRouterRuntime,
+} from "../logger.js";
+/** Re-exports response hook contracts used by AWS Lambda handlers. */
+export type { AppRouterResponseHook, AppRouterResponseHookContext } from "../render.js";
+/** Re-exports build contracts referenced by AWS Lambda handler options. */
+export type { BuiltPrerenderedRoute } from "../build.js";
+/** Re-exports router instrumentation hooks and events for AWS Lambda handlers. */
+export type {
+  RouterInstrumentation,
+  RouterMiddlewareEndInstrumentationEvent,
+  RouterMiddlewareInstrumentationEvent,
+  RouterRequestEndInstrumentationEvent,
+  RouterRequestInstrumentationEvent,
+  RouterRouteEndInstrumentationEvent,
+  RouterRouteInstrumentationEvent,
+  RouterTraceContext,
+} from "../trace.js";
 /** Re-exports app-router import policy controls for AWS Lambda handlers. */
 export type { AppRouterImportPolicy } from "../import-policy.js";
 import {
@@ -36,6 +69,13 @@ import {
   type ResponseSinkStrategy,
 } from "../serve.js";
 
+/** Re-exports request and rendering contracts used by AWS Lambda handlers. */
+export type {
+  AppRouterPrerenderStore,
+  RequestHostPolicy,
+  ResponseSinkStrategy,
+} from "../serve.js";
+
 /**
  * Represents the AWS API Gateway HTTP API v2 event consumed by buffered handlers.
  */
@@ -44,15 +84,15 @@ export interface AwsLambdaHttpEventV2 {
   cookies?: string[] | undefined;
   headers?: Record<string, string | undefined> | undefined;
   isBase64Encoded?: boolean | undefined;
-  rawPath?: string | undefined;
-  rawQueryString?: string | undefined;
-  requestContext?: {
-    http?: {
-      method?: string | undefined;
+  rawPath: string;
+  rawQueryString: string;
+  requestContext: {
+    http: {
+      method: string;
       protocol?: string | undefined;
-    } | undefined;
-  } | undefined;
-  version?: "2.0" | string | undefined;
+    };
+  };
+  version: "2.0";
 }
 
 /**
@@ -156,6 +196,25 @@ export type AwsLambdaStreamingRequestHandler<TContext = unknown> = (
   context: TContext,
 ) => Promise<void>;
 
+const invalidAwsLambdaHttpEventV2Diagnostic =
+  'Expected an AWS Lambda HTTP API payload format 2.0 event with rawPath and requestContext.http.method.';
+
+function invalidAwsLambdaHttpEventV2Result(): AwsLambdaHttpResultV2 {
+  return {
+    body: invalidAwsLambdaHttpEventV2Diagnostic,
+    headers: { "content-type": "text/plain; charset=utf-8" },
+    isBase64Encoded: false,
+    statusCode: 400,
+  };
+}
+
+function invalidAwsLambdaHttpEventV2Response(): Response {
+  return new Response(invalidAwsLambdaHttpEventV2Diagnostic, {
+    headers: { "content-type": "text/plain; charset=utf-8" },
+    status: 400,
+  });
+}
+
 /**
  * Creates a buffered AWS Lambda HTTP API v2 handler for built app-router output.
  *
@@ -165,35 +224,75 @@ export function createAwsLambdaRequestHandler(
   options: AwsLambdaRequestHandlerOptions,
 ): AwsLambdaRequestHandler {
   warnIfImplicitHostTrust(options);
-  const runtimeDirPromise = prepareAwsLambdaRuntimeDir(options);
-  const runtimePreloadPromise = startAwsLambdaRuntimePreload(
-    options,
-    runtimeDirPromise,
-    "middleware",
-  );
-  void runtimePreloadPromise?.catch(() => {});
+  let handler: AwsLambdaRequestHandler | undefined;
 
-  return createAwsLambdaRequestHandlerFromRuntime(
-    options,
-    runtimeDirPromise,
-    runtimePreloadPromise,
-    "middleware",
-  );
+  return async (event) => {
+    try {
+      validateAwsLambdaHttpEventV2(event);
+    } catch {
+      return invalidAwsLambdaHttpEventV2Result();
+    }
+
+    handler ??= (() => {
+      const runtimeDirPromise = prepareAwsLambdaRuntimeDir(options);
+      const runtimePreloadPromise = startAwsLambdaRuntimePreload(options, runtimeDirPromise, "middleware");
+      void runtimePreloadPromise?.catch(() => {});
+      return createAwsLambdaRequestHandlerFromRuntime(
+        options,
+        runtimeDirPromise,
+        runtimePreloadPromise,
+        "middleware",
+      );
+    })();
+
+    return await handler(event);
+  };
 }
 
 /**
- * Creates a buffered AWS Lambda handler after eagerly preparing and preloading the built runtime.
+ * Creates a buffered AWS Lambda handler that starts full runtime preparation after the first valid event.
  *
- * Use this when startup code can await preload work before the first request instead of letting the first invocation share that cost.
+ * Invalid events are rejected before runtime materialization or preload work begins.
  */
 export async function createPreloadedAwsLambdaRequestHandler(
   options: AwsLambdaRequestHandlerOptions,
 ): Promise<AwsLambdaRequestHandler> {
+  warnIfImplicitHostTrust(options);
+  let handler: AwsLambdaRequestHandler | undefined;
+
+  return async (event) => {
+    try {
+      validateAwsLambdaHttpEventV2(event);
+    } catch {
+      return invalidAwsLambdaHttpEventV2Result();
+    }
+
+    handler ??= (() => {
+      const runtimeDirPromise = prepareAwsLambdaRuntimeDir(options);
+      const runtimePreloadPromise = startAwsLambdaRuntimePreload(options, runtimeDirPromise, "all");
+      void runtimePreloadPromise?.catch(() => {});
+      return createAwsLambdaRequestHandlerFromRuntime(
+        options,
+        runtimeDirPromise,
+        runtimePreloadPromise,
+      );
+    })();
+
+    return await handler(event);
+  };
+}
+
+/**
+ * Explicitly materializes and preloads a built Lambda runtime before request handling.
+ *
+ * Call this during controlled Lambda initialization only when the extra startup work is preferable to first-valid-request latency. Request handlers always validate events before they start runtime work.
+ */
+export async function warmAwsLambdaRuntime(
+  options: AwsLambdaRequestHandlerOptions,
+): Promise<void> {
   warnIfImplicitHostTrust(options);
   const runtimeDir = await prepareAwsLambdaRuntimeDir(options);
   await preloadAwsLambdaRuntime(options, runtimeDir);
-
-  return createAwsLambdaRequestHandlerFromRuntime(options, Promise.resolve(runtimeDir));
 }
 
 function createAwsLambdaRequestHandlerFromRuntime(
@@ -203,6 +302,12 @@ function createAwsLambdaRequestHandlerFromRuntime(
   defaultPreloadMode: AwsLambdaDefaultPreloadMode = "all",
 ): AwsLambdaRequestHandler {
   return async (event) => {
+    try {
+      validateAwsLambdaHttpEventV2(event);
+    } catch {
+      return invalidAwsLambdaHttpEventV2Result();
+    }
+
     const startedAt = logNow();
     const phases = createAwsLambdaTimingPhases(options);
     const eventToRequestStartedAt = phaseStartedAt(phases);
@@ -298,39 +403,75 @@ export function createAwsLambdaStreamingRequestHandler<TContext = unknown>(
 ): AwsLambdaStreamingRequestHandler<TContext> {
   warnIfImplicitHostTrust(options);
   const runtime = awsLambdaRuntime();
-  const runtimeDirPromise = prepareAwsLambdaRuntimeDir(options);
-  const runtimePreloadPromise = startAwsLambdaRuntimePreload(
-    options,
-    runtimeDirPromise,
-    "middleware",
-  );
-  void runtimePreloadPromise?.catch(() => {});
-
-  return createAwsLambdaStreamingRequestHandlerFromRuntime(
-    options,
-    runtime,
-    runtimeDirPromise,
-    runtimePreloadPromise,
-    "middleware",
-  );
+  let handler: AwsLambdaStreamingRequestHandler<TContext> | undefined;
+
+  return runtime.streamifyResponse(async (event, responseStream, context) => {
+    try {
+      validateAwsLambdaHttpEventV2(event);
+    } catch {
+      await streamResponseToLambda(
+        invalidAwsLambdaHttpEventV2Response(),
+        responseStream,
+        runtime,
+      );
+      return;
+    }
+
+    handler ??= (() => {
+      const runtimeDirPromise = prepareAwsLambdaRuntimeDir(options);
+      const runtimePreloadPromise = startAwsLambdaRuntimePreload(options, runtimeDirPromise, "middleware");
+      void runtimePreloadPromise?.catch(() => {});
+      return createAwsLambdaStreamingRequestHandlerFromRuntime(
+        options,
+        runtime,
+        runtimeDirPromise,
+        runtimePreloadPromise,
+        "middleware",
+      );
+    })();
+
+    await handler(event, responseStream, context);
+  });
 }
 
 /**
- * Creates a streaming AWS Lambda handler after eagerly preparing and preloading the built runtime.
+ * Creates a streaming AWS Lambda handler that starts full runtime preparation after the first valid event.
+ *
+ * Invalid events are rejected before runtime materialization or preload work begins.
  */
 export async function createPreloadedAwsLambdaStreamingRequestHandler<TContext = unknown>(
   options: AwsLambdaRequestHandlerOptions,
 ): Promise<AwsLambdaStreamingRequestHandler<TContext>> {
   warnIfImplicitHostTrust(options);
   const runtime = awsLambdaRuntime();
-  const runtimeDir = await prepareAwsLambdaRuntimeDir(options);
-  await preloadAwsLambdaRuntime(options, runtimeDir);
+  let handler: AwsLambdaStreamingRequestHandler<TContext> | undefined;
 
-  return createAwsLambdaStreamingRequestHandlerFromRuntime<TContext>(
-    options,
-    runtime,
-    Promise.resolve(runtimeDir),
-  );
+  return runtime.streamifyResponse(async (event, responseStream, context) => {
+    try {
+      validateAwsLambdaHttpEventV2(event);
+    } catch {
+      await streamResponseToLambda(
+        invalidAwsLambdaHttpEventV2Response(),
+        responseStream,
+        runtime,
+      );
+      return;
+    }
+
+    handler ??= (() => {
+      const runtimeDirPromise = prepareAwsLambdaRuntimeDir(options);
+      const runtimePreloadPromise = startAwsLambdaRuntimePreload(options, runtimeDirPromise, "all");
+      void runtimePreloadPromise?.catch(() => {});
+      return createAwsLambdaStreamingRequestHandlerFromRuntime<TContext>(
+        options,
+        runtime,
+        runtimeDirPromise,
+        runtimePreloadPromise,
+      );
+    })();
+
+    await handler(event, responseStream, context);
+  });
 }
 
 function startAwsLambdaRuntimePreload(
@@ -480,6 +621,17 @@ function createAwsLambdaStreamingRequestHandlerFromRuntime<TContext = unknown>(
   defaultPreloadMode: AwsLambdaDefaultPreloadMode = "all",
 ): AwsLambdaStreamingRequestHandler<TContext> {
   return runtime.streamifyResponse(async (event, responseStream, _context) => {
+    try {
+      validateAwsLambdaHttpEventV2(event);
+    } catch {
+      await streamResponseToLambda(
+        invalidAwsLambdaHttpEventV2Response(),
+        responseStream,
+        runtime,
+      );
+      return;
+    }
+
     const startedAt = logNow();
     const phases = createAwsLambdaTimingPhases(options);
     const eventToRequestStartedAt = phaseStartedAt(phases);
@@ -647,6 +799,7 @@ function eventToRequest(
   event: AwsLambdaHttpEventV2,
   options: AwsLambdaRequestHandlerOptions,
 ): Request {
+  validateAwsLambdaHttpEventV2(event);
   const headers = eventHeaders(event);
   const rawHost = lambdaRequestHost(headers, options);
   const host = resolveRequestHost({
@@ -656,12 +809,9 @@ function eventToRequest(
     rawHost: rawHost ?? undefined,
   });
   const protocol = lambdaRequestProtocol(event, headers, options);
-  const rawPath = event.rawPath === undefined || event.rawPath === "" ? "/" : event.rawPath;
-  const rawQueryString =
-    event.rawQueryString === undefined || event.rawQueryString === ""
-      ? ""
-      : `?${event.rawQueryString}`;
-  const method = event.requestContext?.http?.method ?? "GET";
+  const rawPath = event.rawPath;
+  const rawQueryString = event.rawQueryString === "" ? "" : `?${event.rawQueryString}`;
+  const method = event.requestContext.http.method;
   const init: RequestInit = {
     headers,
     method,
@@ -675,6 +825,27 @@ function eventToRequest(
   return new Request(`${protocol}://${host}${rawPath}${rawQueryString}`, init);
 }
 
+function validateAwsLambdaHttpEventV2(event: AwsLambdaHttpEventV2): void {
+  const candidate = event as unknown;
+
+  if (
+    typeof candidate !== "object" ||
+    candidate === null ||
+    (candidate as { version?: unknown }).version !== "2.0" ||
+    typeof (candidate as { rawPath?: unknown }).rawPath !== "string" ||
+    !(candidate as { rawPath: string }).rawPath.startsWith("/") ||
+    typeof (candidate as { rawQueryString?: unknown }).rawQueryString !== "string" ||
+    typeof (candidate as { requestContext?: unknown }).requestContext !== "object" ||
+    (candidate as { requestContext?: unknown }).requestContext === null ||
+    typeof ((candidate as { requestContext: { http?: unknown } }).requestContext.http) !== "object" ||
+    (candidate as { requestContext: { http?: unknown } }).requestContext.http === null ||
+    typeof ((candidate as { requestContext: { http: { method?: unknown } } }).requestContext.http.method) !== "string" ||
+    (candidate as { requestContext: { http: { method: string } } }).requestContext.http.method === ""
+  ) {
+    throw new Error(invalidAwsLambdaHttpEventV2Diagnostic);
+  }
+}
+
 function lambdaRequestHost(
   headers: Headers,
   options: AwsLambdaRequestHandlerOptions,

package/src/adapters/cloudflare.ts

@@ -39,6 +39,65 @@ import type { AppRouterPrerenderStore } from "../serve.js";
 import { emitRouterDevtoolsEvent } from "./devtools.js";
 import { escapeHtmlAttribute, escapeHtmlText } from "@reckona/mreact-shared/html-escape";
 
+/** Re-exports build manifest contracts used by Cloudflare handlers. */
+export type {
+  BuiltPrerenderedRoute,
+  BuiltRouteSourceAnalysisSummary,
+  BuiltServerActionExpressionReference,
+  BuiltServerActionReference,
+  BuiltServerManifest,
+  BuiltServerModuleArtifact,
+  BuiltServerModuleOutput,
+} from "../build.js";
+/** Re-exports client manifest contracts used by Cloudflare handlers. */
+export type { ClientRouteManifestEntry } from "../client.js";
+/** Re-exports route cache policy contracts used by route manifests. */
+export type { RouteCachePolicy } from "../cache.js";
+/** Re-exports logger contracts used by Cloudflare handlers. */
+export type {
+  AppRouterCspInlineNonceWarningLogEvent,
+  AppRouterLogger,
+  AppRouterLogError,
+  AppRouterLogEvent,
+  AppRouterRenderTimingLogEvent,
+  AppRouterRequestEndLogEvent,
+  AppRouterRequestErrorLogEvent,
+  AppRouterRequestStartLogEvent,
+  AppRouterRequestTimingLogEvent,
+  AppRouterRuntime,
+} from "../logger.js";
+/** Re-exports response hook contracts used by Cloudflare handlers. */
+export type { AppRouterResponseHook, AppRouterResponseHookContext } from "../render.js";
+/** Re-exports route contracts used by Cloudflare handlers. */
+export type {
+  AppAssetRoute,
+  AppMetadataRoute,
+  AppRoute,
+  CompiledRouteMatcherEntry,
+  CompiledRouteMatcherArtifact,
+  CompiledRouteMatcherSegment,
+  PageRoute,
+  ServerRoute,
+  RouteSegment,
+} from "../routes.js";
+/** Re-exports prerender store contracts used by Cloudflare handlers. */
+export type { AppRouterPrerenderStore } from "../serve.js";
+/** Re-exports metadata contracts used by Cloudflare route modules. */
+export type {
+  GenerateMetadataContext,
+  MetadataImage,
+  MetadataScalar,
+  MetadataThemeColor,
+  MetadataViewport,
+  RouteHeadDescriptor,
+  RouteMetadata,
+  RouteParams,
+  RouteSecurityHeaders,
+  RouteStrictTransportSecurity,
+} from "../types.js";
+/** Re-exports file convention contracts used by Cloudflare route manifests. */
+export type { AppFileConvention } from "../file-conventions.js";
+
 /**
  * Represents the Cloudflare Worker execution context used by router handlers.
  */

package/src/adapters/edge.ts

@@ -8,6 +8,20 @@ import {
   type AppRouterLogger,
 } from "../logger.js";
 
+/** Re-exports the logger contract used by edge handlers. */
+export type {
+  AppRouterCspInlineNonceWarningLogEvent,
+  AppRouterLogger,
+  AppRouterLogError,
+  AppRouterLogEvent,
+  AppRouterRenderTimingLogEvent,
+  AppRouterRequestEndLogEvent,
+  AppRouterRequestErrorLogEvent,
+  AppRouterRequestStartLogEvent,
+  AppRouterRequestTimingLogEvent,
+  AppRouterRuntime,
+} from "../logger.js";
+
 /**
  * Handles one standard Web `Request` in an edge runtime.
  */

package/src/adapters/node.ts

@@ -15,8 +15,43 @@ import {
 import type { AppRouterResponseHook } from "../render.js";
 import type { RouterInstrumentation } from "../trace.js";
 
-/** Re-exports router instrumentation hooks for Node handlers. */
-export type { RouterInstrumentation } from "../trace.js";
+/** Re-exports cache contracts used by Node handlers. */
+export type { AppRouterCache, AppRouterCacheEntry } from "../cache.js";
+/** Re-exports server action contracts used by Node handlers. */
+export type {
+  AppRouterAllowedServerAction,
+  AppRouterServerActionOptions,
+} from "../actions.js";
+/** Re-exports import policy contracts used by Node handlers. */
+export type { AppRouterImportPolicy } from "../import-policy.js";
+/** Re-exports logger contracts used by Node handlers. */
+export type {
+  AppRouterCspInlineNonceWarningLogEvent,
+  AppRouterLogger,
+  AppRouterLogError,
+  AppRouterLogEvent,
+  AppRouterRenderTimingLogEvent,
+  AppRouterRequestEndLogEvent,
+  AppRouterRequestErrorLogEvent,
+  AppRouterRequestStartLogEvent,
+  AppRouterRequestTimingLogEvent,
+  AppRouterRuntime,
+} from "../logger.js";
+/** Re-exports response hook contracts used by Node handlers. */
+export type { AppRouterResponseHook, AppRouterResponseHookContext } from "../render.js";
+/** Re-exports build contracts referenced by Node handler options. */
+export type { BuiltPrerenderedRoute } from "../build.js";
+/** Re-exports router instrumentation hooks and events for Node handlers. */
+export type {
+  RouterInstrumentation,
+  RouterMiddlewareEndInstrumentationEvent,
+  RouterMiddlewareInstrumentationEvent,
+  RouterRequestEndInstrumentationEvent,
+  RouterRequestInstrumentationEvent,
+  RouterRouteEndInstrumentationEvent,
+  RouterRouteInstrumentationEvent,
+  RouterTraceContext,
+} from "../trace.js";
 import {
   renderBuiltAppRequest,
   resolveRequestHost,
@@ -26,6 +61,13 @@ import {
   type ResponseSinkStrategy,
 } from "../serve.js";
 
+/** Re-exports request and rendering contracts used by Node handlers. */
+export type {
+  AppRouterPrerenderStore,
+  RequestHostPolicy,
+  ResponseSinkStrategy,
+} from "../serve.js";
+
 /**
  * Configures a Node request handler for built app-router output.
  */

package/src/cache.ts

@@ -58,6 +58,7 @@ interface AppRouterCacheState {
 interface RouteCacheContext {
   cache: AppRouterCache;
   cachePolicy?: RouteCachePolicy | undefined;
+  closed?: boolean | undefined;
   revalidatedPaths: Set<string>;
 }
 
@@ -472,15 +473,20 @@ export async function withRouteCacheContext<T>(
   };
 
   return cacheState.storage.run(context, async () => {
-    const value = await fn();
-    const cachePolicy = context.cachePolicy;
-    const revalidatedPaths = Array.from(context.revalidatedPaths);
+    try {
+      const value = await fn();
+      context.closed = true;
+      const cachePolicy = context.cachePolicy;
+      const revalidatedPaths = Array.from(context.revalidatedPaths);
 
-    for (const path of revalidatedPaths) {
-      await context.cache.deleteByPath(path);
-    }
+      for (const path of revalidatedPaths) {
+        await context.cache.deleteByPath(path);
+      }
 
-    return { cachePolicy, revalidatedPaths, value };
+      return { cachePolicy, revalidatedPaths, value };
+    } finally {
+      context.closed = true;
+    }
   });
 }
 
@@ -500,15 +506,17 @@ export function beginRouteCacheContext(cache: AppRouterCache | undefined): {
       return context.cachePolicy;
     },
     async dispose() {
+      context.closed = true;
       const revalidatedPaths = Array.from(context.revalidatedPaths);
-
-      for (const path of revalidatedPaths) {
-        await context.cache.deleteByPath(path);
-      }
-
-      const index = cacheState.activeContexts.lastIndexOf(context);
-      if (index !== -1) {
-        cacheState.activeContexts.splice(index, 1);
+      try {
+        for (const path of revalidatedPaths) {
+          await context.cache.deleteByPath(path);
+        }
+      } finally {
+        const index = cacheState.activeContexts.lastIndexOf(context);
+        if (index !== -1) {
+          cacheState.activeContexts.splice(index, 1);
+        }
       }
 
       return { revalidatedPaths };
@@ -516,8 +524,22 @@ export function beginRouteCacheContext(cache: AppRouterCache | undefined): {
   };
 }
 
-function activeRouteCacheContext(): RouteCacheContext | undefined {
-  return cacheState.storage.getStore() ?? cacheState.activeContexts.at(-1);
+export function activeRouteCacheContext(): RouteCacheContext | undefined {
+  const asyncContext = cacheState.storage.getStore();
+
+  if (asyncContext !== undefined) {
+    return asyncContext.closed === true ? undefined : asyncContext;
+  }
+
+  for (let index = cacheState.activeContexts.length - 1; index >= 0; index -= 1) {
+    const context = cacheState.activeContexts[index];
+
+    if (context?.closed !== true) {
+      return context;
+    }
+  }
+
+  return undefined;
 }
 
 // Host is excluded from the cache key to prevent attacker-supplied Host