@beignet/next 0.0.50 → 0.0.52

package/src/index.ts

@@ -43,6 +43,7 @@ import type {
   StandardSchemaV1,
 } from "@beignet/core/server";
 import { createHealthHandler, createServer } from "@beignet/core/server";
+import type { TracingPort } from "@beignet/core/tracing";
 import type { UploadRouter } from "@beignet/core/uploads";
 import {
   type InferWebhookEvent,
@@ -333,6 +334,7 @@ type OutboxDrainPorts = {
   logger?: OutboxDrainLogger;
   devtools?: OutboxDrainInstrumentation;
   instrumentation?: OutboxDrainInstrumentation;
+  tracing?: TracingPort;
   errorReporter?: ErrorReporterPort;
 };
 
@@ -344,7 +346,10 @@ type OutboxDrainContext = {
 
 type OutboxDrainRuntimeOptions = {
   batchSize?: number;
+  concurrency?: number;
   leaseMs?: number;
+  heartbeatMs?: number;
+  maxActiveMs?: number;
   retryDelayMs?: DrainOutboxOptions["retryDelayMs"];
 };
 
@@ -382,10 +387,16 @@ export type CreateNextOutboxDrainTriggerOptions<
   createContext: () => MaybePromise<Ctx>;
   /** Static registry or lazy loader used to avoid server/provider cycles. */
   registry: OutboxRegistry | (() => MaybePromise<OutboxRegistry>);
-  /** Maximum messages to claim in the deferred drain pass. */
+  /** Maximum eligible messages to handle in the deferred drain pass. */
   batchSize?: number;
+  /** Maximum messages delivered concurrently. Values above one are unordered. */
+  concurrency?: number;
   /** Claim lease duration in milliseconds. */
   leaseMs?: number;
+  /** Serialized claim-renewal interval. Must remain shorter than `leaseMs`. */
+  heartbeatMs?: number;
+  /** Maximum time Beignet renews a claim for one delivery. */
+  maxActiveMs?: number;
   /** Retry delay override passed through to `drainOutbox(...)`. */
   retryDelayMs?: DrainOutboxOptions["retryDelayMs"];
   /**
@@ -436,13 +447,19 @@ export type CreateOutboxDrainRouteOptions<Ctx extends OutboxDrainContext> = {
    */
   secret?: string;
   /**
-   * Maximum messages to claim in one drain pass.
+   * Maximum eligible messages to handle in one drain pass.
    */
   batchSize?: number;
+  /** Maximum messages delivered concurrently. Values above one are unordered. */
+  concurrency?: number;
   /**
    * Claim lease duration in milliseconds.
    */
   leaseMs?: number;
+  /** Serialized claim-renewal interval. Must remain shorter than `leaseMs`. */
+  heartbeatMs?: number;
+  /** Maximum time Beignet renews a claim for one delivery. */
+  maxActiveMs?: number;
   /**
    * Retry delay override passed through to `drainOutbox(...)`.
    */
@@ -589,6 +606,15 @@ export type CreateWebhookRouteOptions<
    * @default false
    */
   allowUnknownEvents?: AllowUnknownEvents;
+  /**
+   * Maximum raw webhook body size in bytes.
+   *
+   * Bodies above this limit are rejected before server resolution, hooks,
+   * context creation, verification, or fulfillment.
+   *
+   * @default 1048576
+   */
+  maxBodyBytes?: number;
   /**
    * App-owned fulfillment handler. The webhook is verified before this runs.
    *
@@ -684,6 +710,16 @@ export type CreatePaymentWebhookRouteOptions<
    * @default "stripe-signature"
    */
   signatureHeader?: string;
+  /**
+   * Maximum raw webhook body size in bytes.
+   *
+   * Signed bodies above this limit are rejected before provider verification
+   * or fulfillment, and before server resolution, hooks, or context creation.
+   * A missing signature takes precedence and cancels the unread body.
+   *
+   * @default 1048576
+   */
+  maxBodyBytes?: number;
   /**
    * App-owned fulfillment handler. The webhook is verified before this runs.
    *
@@ -1100,40 +1136,59 @@ async function storageResponse(
   if (!key) return storageNotFoundResponse();
 
   const object = await storage.get(key);
-  if (object?.visibility !== "public") {
+  if (!object) {
     return storageNotFoundResponse();
   }
-
-  const headers = new Headers(resolveHeaders(options.headers, req));
-  headers.set("content-length", String(object.size));
-  headers.set("last-modified", object.lastModified.toUTCString());
-  if (!headers.has("x-content-type-options")) {
-    headers.set("x-content-type-options", "nosniff");
+  if (object.visibility !== "public") {
+    await object.cancel().catch(() => undefined);
+    return storageNotFoundResponse();
   }
 
-  if (object.contentType && !headers.has("content-type")) {
-    headers.set("content-type", object.contentType);
-  }
+  try {
+    const headers = new Headers(resolveHeaders(options.headers, req));
+    headers.set("content-length", String(object.size));
+    headers.set("last-modified", object.lastModified.toUTCString());
+    if (!headers.has("x-content-type-options")) {
+      headers.set("x-content-type-options", "nosniff");
+    }
 
-  if (!headers.has("content-disposition")) {
-    const contentDisposition = resolveStorageContentDisposition(
-      options,
-      req,
-      object,
-    );
-    if (contentDisposition) {
-      headers.set("content-disposition", contentDisposition);
+    if (object.contentType && !headers.has("content-type")) {
+      headers.set("content-type", object.contentType);
     }
-  }
 
-  if (object.cacheControl && !headers.has("cache-control")) {
-    headers.set("cache-control", object.cacheControl);
-  }
+    if (!headers.has("content-disposition")) {
+      const contentDisposition = resolveStorageContentDisposition(
+        options,
+        req,
+        object,
+      );
+      if (contentDisposition) {
+        headers.set("content-disposition", contentDisposition);
+      }
+    }
 
-  return new Response(includeBody ? object.stream() : null, {
-    status: 200,
-    headers,
-  });
+    if (object.cacheControl && !headers.has("cache-control")) {
+      headers.set("cache-control", object.cacheControl);
+    }
+
+    if (!includeBody) {
+      await object.cancel();
+      return new Response(null, { status: 200, headers });
+    }
+
+    const body = object.stream();
+    try {
+      return new Response(body, { status: 200, headers });
+    } catch (error) {
+      await body.cancel(error).catch(() => undefined);
+      throw error;
+    }
+  } catch (error) {
+    if (!object.bodyUsed) {
+      await object.cancel(error).catch(() => undefined);
+    }
+    throw error;
+  }
 }
 
 function currentRequestServer(req: Request): OpenAPIServer {
@@ -1382,6 +1437,7 @@ type OperationalErrorCode =
   | "CRON_SECRET_NOT_CONFIGURED"
   | "OUTBOX_DRAIN_FAILED"
   | "PAYMENT_WEBHOOK_BODY_READ_FAILED"
+  | "PAYMENT_WEBHOOK_BODY_TOO_LARGE"
   | "PAYMENT_WEBHOOK_CONTEXT_FAILED"
   | "PAYMENT_WEBHOOK_HANDLER_FAILED"
   | "PAYMENT_WEBHOOK_SIGNATURE_MISSING"
@@ -1389,6 +1445,7 @@ type OperationalErrorCode =
   | "SCHEDULE_FAILED"
   | "UNAUTHORIZED"
   | "WEBHOOK_BODY_READ_FAILED"
+  | "WEBHOOK_BODY_TOO_LARGE"
   | "WEBHOOK_CONTEXT_FAILED"
   | "WEBHOOK_HANDLER_FAILED"
   | "WEBHOOK_VERIFICATION_FAILED";
@@ -1431,14 +1488,94 @@ function toHttpResponseHeaders(
  * creation then receives a rehydrated request carrying the same method, URL,
  * headers, and raw body.
  */
-function toContextRequest(req: Request, rawBody: string): HttpRequestLike {
-  return toRequestLike(
-    new Request(req.url, {
-      method: req.method,
-      headers: req.headers,
-      body: rawBody,
-    }),
-  );
+function rehydrateWebhookRequest(req: Request, rawBody: string): Request {
+  return new Request(req.url, {
+    method: req.method,
+    headers: req.headers,
+    body: rawBody,
+    signal: req.signal,
+  });
+}
+
+const DEFAULT_WEBHOOK_BODY_MAX_BYTES = 1024 * 1024;
+
+class WebhookBodyTooLargeError extends Error {
+  constructor(readonly maxBytes: number) {
+    super("Webhook body exceeds the configured size limit.");
+    this.name = "WebhookBodyTooLargeError";
+  }
+}
+
+function webhookBodyLimit(maxBytes: number | undefined): number {
+  const resolved = maxBytes ?? DEFAULT_WEBHOOK_BODY_MAX_BYTES;
+  if (!Number.isFinite(resolved) || resolved <= 0) {
+    throw new Error("Webhook maxBodyBytes must be a positive number.");
+  }
+  return resolved;
+}
+
+function cancelWebhookBody(
+  source: { cancel(reason?: unknown): Promise<void> },
+  reason: unknown,
+): void {
+  try {
+    void source.cancel(reason).catch(() => {});
+  } catch {
+    // Cancellation is best-effort and must not replace the selected response.
+  }
+}
+
+function cancelWebhookRequestBody(req: HttpRequestLike, reason: unknown): void {
+  const body = req.raw?.body ?? nativeRequestOf(req).body;
+  if (body) cancelWebhookBody(body, reason);
+}
+
+async function readWebhookBody(
+  req: HttpRequestLike,
+  maxBytes: number,
+): Promise<string> {
+  const body = req.raw?.body ?? nativeRequestOf(req).body;
+  const contentLength = req.headers.get("content-length");
+
+  if (contentLength !== null) {
+    const declaredBytes = Number(contentLength);
+    if (Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+      const error = new WebhookBodyTooLargeError(maxBytes);
+      if (body) cancelWebhookBody(body, error);
+      throw error;
+    }
+  }
+
+  if (!body) {
+    const text = await req.text();
+    if (new TextEncoder().encode(text).byteLength > maxBytes) {
+      throw new WebhookBodyTooLargeError(maxBytes);
+    }
+    return text;
+  }
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let receivedBytes = 0;
+  let text = "";
+
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+
+      receivedBytes += result.value.byteLength;
+      if (receivedBytes > maxBytes) {
+        const error = new WebhookBodyTooLargeError(maxBytes);
+        cancelWebhookBody(reader, error);
+        throw error;
+      }
+      text += decoder.decode(result.value, { stream: true });
+    }
+    return text + decoder.decode();
+  } finally {
+    reader.releaseLock();
+  }
 }
 
 function headersToRecord(headers: Headers): Record<string, string> {
@@ -1532,9 +1669,15 @@ async function runOutboxDrainWithContext(
     eventBus: ctx.ports.eventBus,
     jobs: ctx.ports.jobs,
     batchSize: options.batchSize,
+    concurrency: options.concurrency,
     leaseMs: options.leaseMs,
+    heartbeatMs: options.heartbeatMs,
+    maxActiveMs: options.maxActiveMs,
     retryDelayMs: options.retryDelayMs,
-    instrumentation: resolveProviderInstrumentationPort(ctx.ports),
+    instrumentation: {
+      instrumentation: resolveProviderInstrumentationPort(ctx.ports),
+      tracing: ctx.ports.tracing,
+    },
     instrumentationContext: {
       requestId: ctx.requestId,
       traceId: ctx.traceId,
@@ -1577,10 +1720,48 @@ async function runOutboxDrainWithContext(
         },
       });
     },
-    async onSettlementError(settlementError, message) {
+    async onLeaseError(failure) {
+      const outcome =
+        failure.state === "lost"
+          ? "leaseLost"
+          : failure.state === "recovered"
+            ? "leaseRecovered"
+            : "leaseDegraded";
       await tryReportException({
         reporter: ctx.ports.errorReporter,
-        error: settlementError,
+        error: failure.error,
+        reportOptions: {
+          level: failure.state === "lost" ? "error" : "warning",
+          mechanism,
+          handled: failure.state !== "lost",
+          requestId: ctx.requestId,
+          traceId: ctx.traceId,
+          tags: {
+            "beignet.kind": "outbox",
+            "beignet.outbox.kind": failure.message.kind,
+            "beignet.outbox.name": failure.message.name,
+            "beignet.outbox.outcome": outcome,
+          },
+          contexts: {
+            outbox: {
+              messageId: failure.message.id,
+              kind: failure.message.kind,
+              name: failure.message.name,
+              attempts: failure.message.attempts,
+              maxAttempts: failure.message.maxAttempts,
+              operation: failure.operation,
+              state: failure.state,
+              confirmedLost: failure.confirmedLost,
+              outcome,
+            },
+          },
+        },
+      });
+    },
+    async onSettlementError(failure) {
+      await tryReportException({
+        reporter: ctx.ports.errorReporter,
+        error: failure.error,
         reportOptions: {
           level: "error",
           mechanism,
@@ -1589,17 +1770,19 @@ async function runOutboxDrainWithContext(
           traceId: ctx.traceId,
           tags: {
             "beignet.kind": "outbox",
-            "beignet.outbox.kind": message.kind,
-            "beignet.outbox.name": message.name,
+            "beignet.outbox.kind": failure.message.kind,
+            "beignet.outbox.name": failure.message.name,
             "beignet.outbox.outcome": "settlementFailed",
           },
           contexts: {
             outbox: {
-              messageId: message.id,
-              kind: message.kind,
-              name: message.name,
-              attempts: message.attempts,
-              maxAttempts: message.maxAttempts,
+              messageId: failure.message.id,
+              kind: failure.message.kind,
+              name: failure.message.name,
+              attempts: failure.message.attempts,
+              maxAttempts: failure.message.maxAttempts,
+              operation: failure.operation,
+              deliverySucceeded: failure.deliverySucceeded,
               outcome: "settlementFailed",
             },
           },
@@ -1614,7 +1797,7 @@ async function runOutboxDrainWithContext(
       watcher: "outbox",
       name: "outbox.drain",
       label: "Outbox drain",
-      summary: `${result.delivered} delivered, ${result.retried} retried, ${result.deadLettered} dead-lettered`,
+      summary: `${result.delivered} delivered, ${result.retried} retried, ${result.deadLettered} dead-lettered, ${result.settlementFailed} settlement-uncertain, ${result.leaseLost} lease-lost`,
       requestId: ctx.requestId,
       traceId: ctx.traceId,
       details: result,
@@ -1628,6 +1811,16 @@ async function runOutboxDrainWithContext(
   return result;
 }
 
+function hasUncertainOutboxResult(result: DrainOutboxResult): boolean {
+  return result.settlementFailed > 0 || result.leaseLost > 0;
+}
+
+function uncertainOutboxError(result: DrainOutboxResult): Error {
+  return new Error(
+    `Outbox drain completed with ${result.settlementFailed} settlement failure(s) and ${result.leaseLost} lost lease(s).`,
+  );
+}
+
 async function resolveOutboxRegistry(
   source: OutboxRegistry | (() => MaybePromise<OutboxRegistry>),
 ): Promise<OutboxRegistry> {
@@ -1712,12 +1905,16 @@ export function createNextOutboxDrainTrigger<Ctx extends OutboxDrainContext>(
         try {
           ctx = await options.createContext();
           const registry = await resolveOutboxRegistry(options.registry);
-          await runOutboxDrainWithContext(
+          const result = await runOutboxDrainWithContext(
             ctx,
             registry,
             options,
             "beignet.outbox.next.after",
           );
+          if (hasUncertainOutboxResult(result)) {
+            const error = uncertainOutboxError(result);
+            await notifyDeferredWorkError(options.onError, error);
+          }
         } catch (error) {
           if (ctx) {
             try {
@@ -1777,6 +1974,22 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
         "beignet.outbox.next",
       );
 
+      if (hasUncertainOutboxResult(result)) {
+        return routeJson(
+          {
+            ok: false,
+            error: {
+              code: "OUTBOX_DRAIN_UNCERTAIN",
+              message:
+                "Outbox drain completed with unconfirmed delivery state.",
+            },
+            result,
+          },
+          500,
+          headers,
+        );
+      }
+
       return routeJson(
         {
           ok: true,
@@ -1862,8 +2075,9 @@ export function createOutboxDrainRoute<Ctx extends OutboxDrainContext>(
 /**
  * Create a Next.js POST handler for generic verified inbound webhooks.
  *
- * The route reads the raw request body as text, normalizes request headers,
- * builds app context from the real request through
+ * The route bounds and reads the raw request body before resolving the server,
+ * then normalizes request headers and builds app context from a rehydrated
+ * request through
  * `server.createRequestContext(...)`, verifies the event through the webhook
  * definition or a context-aware verifier, validates the matching event
  * payload schema, and delegates fulfillment to app code.
@@ -1877,28 +2091,43 @@ export function createWebhookRoute<
 ): {
   POST: (req: Request) => Promise<Response>;
 } {
+  const maxBodyBytes = webhookBodyLimit(options.maxBodyBytes);
+  const preflightBodies = new WeakMap<Request, string>();
+
   const handleWebhookRequest = async ({
     req,
     ctx,
+    rawBody: providedRawBody,
   }: {
     req: HttpRequestLike;
     ctx: Ctx;
+    rawBody?: string;
   }): Promise<Response> => {
     const nativeReq = nativeRequestOf(req);
     const headers = resolveHeaders(options.headers, nativeReq);
     const requestHeaders = headersToRecord(new Headers(req.headers));
 
-    let rawBody: string;
+    let rawBody = providedRawBody ?? preflightBodies.get(nativeReq);
+    preflightBodies.delete(nativeReq);
 
-    try {
-      rawBody = await req.text();
-    } catch {
-      return operationalErrorJson(
-        "WEBHOOK_BODY_READ_FAILED",
-        "Webhook body read failed.",
-        400,
-        headers,
-      );
+    if (rawBody === undefined) {
+      try {
+        rawBody = await readWebhookBody(req, maxBodyBytes);
+      } catch (error) {
+        return error instanceof WebhookBodyTooLargeError
+          ? operationalErrorJson(
+              "WEBHOOK_BODY_TOO_LARGE",
+              "Webhook body exceeds the configured size limit.",
+              413,
+              headers,
+            )
+          : operationalErrorJson(
+              "WEBHOOK_BODY_READ_FAILED",
+              "Webhook body read failed.",
+              400,
+              headers,
+            );
+      }
     }
 
     let event: WebhookRouteHandlerArgs<
@@ -2009,32 +2238,42 @@ export function createWebhookRoute<
 
   return {
     POST: async (req) => {
-      const server = await resolveServerSource(options.server);
-
-      const pipelined = runPipeline(server);
-      if (pipelined) return pipelined(req);
-
-      // Minimal servers without rawRoute(...) — usually test fakes — build
-      // context directly and run the same handler outside the hooks pipeline.
       const headers = resolveHeaders(options.headers, req);
 
       let rawBody: string;
       try {
-        rawBody = await req.text();
-      } catch {
-        return operationalErrorJson(
-          "WEBHOOK_BODY_READ_FAILED",
-          "Webhook body read failed.",
-          400,
-          headers,
-        );
+        rawBody = await readWebhookBody(toRequestLike(req), maxBodyBytes);
+      } catch (error) {
+        return error instanceof WebhookBodyTooLargeError
+          ? operationalErrorJson(
+              "WEBHOOK_BODY_TOO_LARGE",
+              "Webhook body exceeds the configured size limit.",
+              413,
+              headers,
+            )
+          : operationalErrorJson(
+              "WEBHOOK_BODY_READ_FAILED",
+              "Webhook body read failed.",
+              400,
+              headers,
+            );
+      }
+
+      const contextRequest = rehydrateWebhookRequest(req, rawBody);
+      const server = await resolveServerSource(options.server);
+      const pipelined = runPipeline(server);
+      if (pipelined) {
+        preflightBodies.set(contextRequest, rawBody);
+        return pipelined(contextRequest);
       }
 
-      const contextRequest = toContextRequest(req, rawBody);
+      // Minimal servers without rawRoute(...) — usually test fakes — build
+      // context directly and run the same handler outside the hooks pipeline.
+      const requestLike = toRequestLike(contextRequest);
 
       let ctx: Ctx;
       try {
-        ctx = await server.createRequestContext(contextRequest);
+        ctx = await server.createRequestContext(requestLike);
       } catch {
         return operationalErrorJson(
           "WEBHOOK_CONTEXT_FAILED",
@@ -2044,7 +2283,11 @@ export function createWebhookRoute<
         );
       }
 
-      return handleWebhookRequest({ req: toContextRequest(req, rawBody), ctx });
+      return handleWebhookRequest({
+        req: requestLike,
+        ctx,
+        rawBody,
+      });
     },
   };
 }
@@ -2052,8 +2295,9 @@ export function createWebhookRoute<
 /**
  * Create a Next.js POST handler for provider-verified payment webhooks.
  *
- * The route extracts the provider signature header, reads the raw request
- * body as text, builds app context from the real request through
+ * The route checks the provider signature header and bounds the raw request
+ * body before resolving the server, then builds app context from a rehydrated
+ * request through
  * `server.createRequestContext(...)`, verifies the event through
  * `ctx.ports.payments`, and then delegates fulfillment to app code. This is the canonical helper for Beignet
  * billing flows backed by `PaymentsPort`. Keep this route on the Node.js
@@ -2067,19 +2311,27 @@ export function createPaymentWebhookRoute<
   POST: (req: Request) => Promise<Response>;
 } {
   const signatureHeader = options.signatureHeader ?? "stripe-signature";
+  const maxBodyBytes = webhookBodyLimit(options.maxBodyBytes);
+  const preflightBodies = new WeakMap<Request, string>();
 
   const handlePaymentWebhook = async ({
     req,
     ctx,
+    rawBody: providedRawBody,
   }: {
     req: HttpRequestLike;
     ctx: Ctx;
+    rawBody?: string;
   }): Promise<Response> => {
     const nativeReq = nativeRequestOf(req);
     const headers = resolveHeaders(options.headers, nativeReq);
     const signature = new Headers(req.headers).get(signatureHeader);
 
     if (!signature) {
+      cancelWebhookRequestBody(
+        req,
+        new Error(`Missing ${signatureHeader} header.`),
+      );
       return operationalErrorJson(
         "PAYMENT_WEBHOOK_SIGNATURE_MISSING",
         `Missing ${signatureHeader} header.`,
@@ -2088,17 +2340,27 @@ export function createPaymentWebhookRoute<
       );
     }
 
-    let rawBody: string;
+    let rawBody = providedRawBody ?? preflightBodies.get(nativeReq);
+    preflightBodies.delete(nativeReq);
 
-    try {
-      rawBody = await req.text();
-    } catch {
-      return operationalErrorJson(
-        "PAYMENT_WEBHOOK_BODY_READ_FAILED",
-        "Payment webhook body read failed.",
-        400,
-        headers,
-      );
+    if (rawBody === undefined) {
+      try {
+        rawBody = await readWebhookBody(req, maxBodyBytes);
+      } catch (error) {
+        return error instanceof WebhookBodyTooLargeError
+          ? operationalErrorJson(
+              "PAYMENT_WEBHOOK_BODY_TOO_LARGE",
+              "Payment webhook body exceeds the configured size limit.",
+              413,
+              headers,
+            )
+          : operationalErrorJson(
+              "PAYMENT_WEBHOOK_BODY_READ_FAILED",
+              "Payment webhook body read failed.",
+              400,
+              headers,
+            );
+      }
     }
 
     let event: PaymentWebhookEvent;
@@ -2181,17 +2443,15 @@ export function createPaymentWebhookRoute<
 
   return {
     POST: async (req) => {
-      const server = await resolveServerSource(options.server);
-
-      const pipelined = runPipeline(server);
-      if (pipelined) return pipelined(req);
-
-      // Minimal servers without rawRoute(...) — usually test fakes — build
-      // context directly and run the same handler outside the hooks pipeline.
-      // The signature gate runs first so no context is created without one.
       const headers = resolveHeaders(options.headers, req);
 
       if (!req.headers.get(signatureHeader)) {
+        if (req.body) {
+          cancelWebhookBody(
+            req.body,
+            new Error(`Missing ${signatureHeader} header.`),
+          );
+        }
         return operationalErrorJson(
           "PAYMENT_WEBHOOK_SIGNATURE_MISSING",
           `Missing ${signatureHeader} header.`,
@@ -2202,19 +2462,38 @@ export function createPaymentWebhookRoute<
 
       let rawBody: string;
       try {
-        rawBody = await req.text();
-      } catch {
-        return operationalErrorJson(
-          "PAYMENT_WEBHOOK_BODY_READ_FAILED",
-          "Payment webhook body read failed.",
-          400,
-          headers,
-        );
+        rawBody = await readWebhookBody(toRequestLike(req), maxBodyBytes);
+      } catch (error) {
+        return error instanceof WebhookBodyTooLargeError
+          ? operationalErrorJson(
+              "PAYMENT_WEBHOOK_BODY_TOO_LARGE",
+              "Payment webhook body exceeds the configured size limit.",
+              413,
+              headers,
+            )
+          : operationalErrorJson(
+              "PAYMENT_WEBHOOK_BODY_READ_FAILED",
+              "Payment webhook body read failed.",
+              400,
+              headers,
+            );
       }
 
+      const contextRequest = rehydrateWebhookRequest(req, rawBody);
+      const server = await resolveServerSource(options.server);
+      const pipelined = runPipeline(server);
+      if (pipelined) {
+        preflightBodies.set(contextRequest, rawBody);
+        return pipelined(contextRequest);
+      }
+
+      // Minimal servers without rawRoute(...) — usually test fakes — build
+      // context directly and run the same handler outside the hooks pipeline.
+      const requestLike = toRequestLike(contextRequest);
+
       let ctx: Ctx;
       try {
-        ctx = await server.createRequestContext(toContextRequest(req, rawBody));
+        ctx = await server.createRequestContext(requestLike);
       } catch {
         return operationalErrorJson(
           "PAYMENT_WEBHOOK_CONTEXT_FAILED",
@@ -2224,7 +2503,11 @@ export function createPaymentWebhookRoute<
         );
       }
 
-      return handlePaymentWebhook({ req: toContextRequest(req, rawBody), ctx });
+      return handlePaymentWebhook({
+        req: requestLike,
+        ctx,
+        rawBody,
+      });
     },
   };
 }