@beignet/core 0.0.27 → 0.0.28

package/src/server/server.ts

@@ -53,6 +53,7 @@ import type {
   HttpRequestLike,
   HttpResponse,
   HttpResponseLike,
+  RequestStageTimings,
   ResolvedRoute,
   RouteHook,
   ServerCaughtErrorHook,
@@ -61,6 +62,11 @@ import type {
 } from "./http.js";
 import type { ServerInstrumentationOptions } from "./instrumentation.js";
 import { createServerInstrumentation } from "./instrumentation.js";
+import {
+  getResponseFinalizerHook,
+  type ResponseFinalizerResponseOwner,
+  type ResponseFinalizerValidationState,
+} from "./internal-hooks.js";
 import {
   loadProviderConfig,
   parseStandardSchema,
@@ -399,6 +405,30 @@ interface RouteBuilder<Ctx, C extends HttpContractConfig> {
   ) => (req: HttpRequestLike) => Promise<HttpResponse>;
 }
 
+/**
+ * Identity and hook metadata for a raw route.
+ *
+ * Raw routes are mounted by the adapter at their own path, so `method` and
+ * `path` describe the route to hooks, instrumentation, and error mapping
+ * instead of driving routing. `metadata` feeds metadata-driven hooks exactly
+ * like contract metadata does, for example `rateLimit` and `idempotency`.
+ */
+export type RawRouteInit = {
+  name: string;
+  method: HttpContractConfig["method"];
+  path: string;
+  metadata?: HttpContractConfig["metadata"];
+};
+
+/**
+ * Builder returned by `server.rawRoute(...)`.
+ */
+export interface RawRouteBuilder<Ctx> {
+  handle: (
+    fn: Handler<Ctx, HttpContractConfig>,
+  ) => (req: HttpRequestLike) => Promise<HttpResponse>;
+}
+
 /**
  * Runtime server object returned by `createServer(...)`.
  */
@@ -417,6 +447,21 @@ export interface ServerInstance<
   route: <CLike extends ContractLike>(
     contractLike: CLike,
   ) => RouteBuilder<Ctx, ResolveContract<CLike>>;
+  /**
+   * Build a handler for a route that cannot be a contract — webhooks,
+   * third-party auth callbacks, streaming endpoints — that still runs the
+   * whole server pipeline: correlation, `onRequest`, route hooks,
+   * `beforeHandle`, `beforeSend`, `afterSend`, context creation,
+   * instrumentation, and framework error mapping.
+   *
+   * Request parsing and validation are skipped and the request body is left
+   * unconsumed, so the handler owns body reading — for example webhook
+   * signature verification over the exact raw bytes. Metadata-driven hooks
+   * such as rate limiting and idempotency read `init.metadata`. Raw routes
+   * are not added to the route registry; mount the returned handler at the
+   * route's own path.
+   */
+  rawRoute: (init: RawRouteInit) => RawRouteBuilder<Ctx>;
   /**
    * Build a fully assembled request context from a framework-neutral request.
    *
@@ -475,7 +520,7 @@ type ExecutionResult<Ctx> = {
   owner?: ResponseOwner;
 };
 
-type ResponseOwner = "route" | "framework" | "transport";
+type ResponseOwner = ResponseFinalizerResponseOwner;
 
 type CompiledPath = {
   keys: string[];
@@ -1125,6 +1170,12 @@ function createRequestExecutor<
   routeHooks: readonly RouteHook<unknown, object>[] = [],
   optionsOverrides?: {
     skipRoutePreparation?: boolean;
+    /**
+     * Run the route through the full hook pipeline without contract
+     * preparation: no query/path/header/body parsing or validation, and the
+     * request body is left unconsumed for the handler.
+     */
+    rawRoute?: boolean;
   },
 ): (
   target: ExecutionTarget<Ctx, C>,
@@ -1146,6 +1197,27 @@ function createRequestExecutor<
     let headersValue: HandlerArgs<Ctx, C>["headers"] | undefined;
     let bodyValue: HandlerArgs<Ctx, C>["body"] | undefined;
     const startedAt = Date.now();
+    // Stage timings accumulate because retries re-enter the send phase and
+    // beforeHandle spans the route-hook and server-hook loops.
+    const stages: RequestStageTimings = {
+      onRequestMs: 0,
+      parseMs: 0,
+      contextMs: 0,
+      beforeHandleMs: 0,
+      handlerMs: 0,
+      sendMs: 0,
+    };
+    const timeStage = async <T>(
+      stage: keyof RequestStageTimings,
+      run: () => Promise<T> | T,
+    ): Promise<T> => {
+      const stageStartedAt = performance.now();
+      try {
+        return await run();
+      } finally {
+        stages[stage] += performance.now() - stageStartedAt;
+      }
+    };
 
     const resolveErrorResult = async (
       error: unknown,
@@ -1485,8 +1557,64 @@ function createRequestExecutor<
         }
       };
 
+      const applyResponseFinalizerHooks = async (
+        initialResult: ExecutionResult<Ctx>,
+        allowRetry: boolean,
+        responseValidation: ResponseFinalizerValidationState,
+      ): Promise<ExecutionResult<Ctx>> => {
+        const response = normalizeHttpResponse(initialResult.response);
+        const native = isWebResponse(response);
+        const owner = responseOwnerFor(response, initialResult.owner);
+
+        try {
+          for (const hook of hooks) {
+            const finalizer = getResponseFinalizerHook<Ctx>(hook);
+            if (!finalizer) continue;
+            await finalizer({
+              req,
+              ctx: initialResult.ctx,
+              contract,
+              path: pathValue,
+              query: queryValue,
+              headers: headersValue,
+              body: bodyValue,
+              response: responseForHooks(response),
+              error: initialResult.error,
+              native: native ? true : undefined,
+              owner,
+              responseValidation,
+            });
+          }
+
+          return {
+            ...initialResult,
+            response,
+          };
+        } catch (error) {
+          const mapped = await resolveErrorResult(
+            error,
+            initialResult.ctx,
+            pathValue,
+            queryValue,
+            headersValue,
+            bodyValue,
+            { owner: "framework" },
+          );
+          if (!allowRetry) {
+            return mapped;
+          }
+          const transformed = await applyTransformHooks(mapped, true);
+          return applyResponseFinalizerHooks(
+            transformed,
+            false,
+            "not-applicable",
+          );
+        }
+      };
+
       let result: ExecutionResult<Ctx> | undefined;
 
+      const onRequestStartedAt = performance.now();
       for (const hook of hooks) {
         if (!hook.onRequest) continue;
         try {
@@ -1517,14 +1645,14 @@ function createRequestExecutor<
           break;
         }
       }
+      stages.onRequestMs = performance.now() - onRequestStartedAt;
 
       if (!result) {
         if (optionsOverrides?.skipRoutePreparation) {
           let createdCtx!: Ctx;
           try {
-            createdCtx = await contextRuntime.createRequestContext(
-              req,
-              contract,
+            createdCtx = await timeStage("contextMs", () =>
+              contextRuntime.createRequestContext(req, contract),
             );
             baseCtx = createdCtx;
           } catch (error) {
@@ -1544,15 +1672,17 @@ function createRequestExecutor<
               result = {
                 ctx: createdCtx,
                 response: normalizeHttpResponse(
-                  await userHandler({
-                    req,
-                    ctx: createdCtx,
-                    contract,
-                    path: {} as HandlerArgs<Ctx, C>["path"],
-                    query: {} as HandlerArgs<Ctx, C>["query"],
-                    headers: rawHeaders as HandlerArgs<Ctx, C>["headers"],
-                    body: undefined as HandlerArgs<Ctx, C>["body"],
-                  }),
+                  await timeStage("handlerMs", () =>
+                    userHandler({
+                      req,
+                      ctx: createdCtx,
+                      contract,
+                      path: {} as HandlerArgs<Ctx, C>["path"],
+                      query: {} as HandlerArgs<Ctx, C>["query"],
+                      headers: rawHeaders as HandlerArgs<Ctx, C>["headers"],
+                      body: undefined as HandlerArgs<Ctx, C>["body"],
+                    }),
+                  ),
                 ),
                 owner: "framework",
               };
@@ -1569,6 +1699,7 @@ function createRequestExecutor<
             }
           }
         } else {
+          const parseStartedAt = performance.now();
           const rawQuery: Record<string, string | string[]> = {};
           for (const key of new Set(url.searchParams.keys())) {
             const values = url.searchParams.getAll(key);
@@ -1641,7 +1772,9 @@ function createRequestExecutor<
 
           // biome-ignore lint/suspicious/noExplicitAny: Type will be narrowed by schema validation
           let body: any;
-          if (!result) {
+          // Raw routes own body consumption: the handler reads `req` itself,
+          // for example to verify a webhook signature over the exact bytes.
+          if (!result && !optionsOverrides?.rawRoute) {
             try {
               body = await parseBody(req, maxRequestBodyBytes);
             } catch (error) {
@@ -1708,6 +1841,8 @@ function createRequestExecutor<
             }
           }
 
+          stages.parseMs = performance.now() - parseStartedAt;
+
           if (!result) {
             pathValue = path;
             queryValue = query;
@@ -1716,9 +1851,8 @@ function createRequestExecutor<
 
             let createdCtx!: Ctx;
             try {
-              createdCtx = await contextRuntime.createRequestContext(
-                req,
-                contract,
+              createdCtx = await timeStage("contextMs", () =>
+                contextRuntime.createRequestContext(req, contract),
               );
               baseCtx = createdCtx;
             } catch (error) {
@@ -1745,10 +1879,10 @@ function createRequestExecutor<
               };
 
               let currentCtx = createdCtx;
-              for (const hook of hooks) {
-                if (!hook.beforeHandle) continue;
+              const beforeHandleStartedAt = performance.now();
+              for (const hook of routeHooks) {
                 try {
-                  const hookResult = await hook.beforeHandle({
+                  const additions = await hook.resolve({
                     req,
                     ctx: currentCtx,
                     contract,
@@ -1757,33 +1891,11 @@ function createRequestExecutor<
                     headers,
                     body,
                   });
-                  if (isWebResponse(hookResult)) {
-                    result = {
-                      ctx: currentCtx,
-                      response: hookResult,
-                      owner: "transport",
-                    };
-                    break;
-                  }
-                  if (isHttpResponseLike(hookResult)) {
-                    result = {
-                      ctx: currentCtx,
-                      response: normalizeResponse(hookResult),
-                      owner: "framework",
-                    };
-                    break;
-                  }
-                  if (hookResult?.ctx !== undefined) {
-                    currentCtx = contextRuntime.finalizeContext(hookResult.ctx);
-                  }
-                  if (hookResult?.response) {
-                    const response = normalizeHttpResponse(hookResult.response);
-                    result = {
-                      ctx: currentCtx,
-                      response,
-                      owner: responseOwnerFor(response, "framework"),
-                    };
-                    break;
+                  if (additions && typeof additions === "object") {
+                    currentCtx = contextRuntime.finalizeContext({
+                      ...(currentCtx as object),
+                      ...additions,
+                    } as Ctx);
                   }
                 } catch (error) {
                   result = await resolveErrorResult(
@@ -1800,9 +1912,10 @@ function createRequestExecutor<
               }
 
               if (!result) {
-                for (const hook of routeHooks) {
+                for (const hook of hooks) {
+                  if (!hook.beforeHandle) continue;
                   try {
-                    const additions = await hook.resolve({
+                    const hookResult = await hook.beforeHandle({
                       req,
                       ctx: currentCtx,
                       contract,
@@ -1811,11 +1924,37 @@ function createRequestExecutor<
                       headers,
                       body,
                     });
-                    if (additions && typeof additions === "object") {
-                      currentCtx = contextRuntime.finalizeContext({
-                        ...(currentCtx as object),
-                        ...additions,
-                      } as Ctx);
+                    if (isWebResponse(hookResult)) {
+                      result = {
+                        ctx: currentCtx,
+                        response: hookResult,
+                        owner: "transport",
+                      };
+                      break;
+                    }
+                    if (isHttpResponseLike(hookResult)) {
+                      result = {
+                        ctx: currentCtx,
+                        response: normalizeResponse(hookResult),
+                        owner: "framework",
+                      };
+                      break;
+                    }
+                    if (hookResult?.ctx !== undefined) {
+                      currentCtx = contextRuntime.finalizeContext(
+                        hookResult.ctx,
+                      );
+                    }
+                    if (hookResult?.response) {
+                      const response = normalizeHttpResponse(
+                        hookResult.response,
+                      );
+                      result = {
+                        ctx: currentCtx,
+                        response,
+                        owner: responseOwnerFor(response, "framework"),
+                      };
+                      break;
                     }
                   } catch (error) {
                     result = await resolveErrorResult(
@@ -1831,6 +1970,7 @@ function createRequestExecutor<
                   }
                 }
               }
+              stages.beforeHandleMs = performance.now() - beforeHandleStartedAt;
 
               if (!result) {
                 // Hooks may have elevated the actor or resolved a tenant.
@@ -1845,7 +1985,9 @@ function createRequestExecutor<
                   result = {
                     ctx: currentCtx,
                     response: normalizeHttpResponse(
-                      await userHandler({ ...baseArgs, ctx: currentCtx }),
+                      await timeStage("handlerMs", () =>
+                        userHandler({ ...baseArgs, ctx: currentCtx }),
+                      ),
                     ),
                   };
                 } catch (error) {
@@ -1864,12 +2006,21 @@ function createRequestExecutor<
         }
       }
 
+      const sendStartedAt = performance.now();
       result = await applyTransformHooks(result, true);
 
       let finalResponse = normalizeHttpResponse(result.response);
       let finalError = result.error;
       let finalOwner = responseOwnerFor(finalResponse, result.owner);
+      let responseValidation: ResponseFinalizerValidationState =
+        "not-applicable";
       if (
+        finalOwner === "route" &&
+        !isWebResponse(finalResponse) &&
+        !(options.validateResponses ?? true)
+      ) {
+        responseValidation = "disabled";
+      } else if (
         finalOwner === "route" &&
         !isWebResponse(finalResponse) &&
         (options.validateResponses ?? true)
@@ -1880,33 +2031,52 @@ function createRequestExecutor<
             finalResponse,
             target.responseValidationExemptStatus,
           );
+          result = {
+            ...result,
+            response: finalResponse,
+          };
+          responseValidation = "validated";
         } catch (error) {
           if (error instanceof ResponseContractViolationError) {
-            result = await applyTransformHooks(
-              {
-                ctx: result.ctx,
-                response: toContractViolationResponse(error),
-                error,
-                owner: "framework",
-              },
-              false,
-            );
+            result = {
+              ctx: result.ctx,
+              response: toContractViolationResponse(error),
+              error,
+              owner: "framework",
+            };
+            finalResponse = normalizeHttpResponse(result.response);
+            finalError = result.error;
+            finalOwner = responseOwnerFor(finalResponse, result.owner);
+            result = await applyTransformHooks(result, true);
             finalResponse = normalizeHttpResponse(result.response);
             finalError = result.error;
             finalOwner = responseOwnerFor(finalResponse, result.owner);
+            responseValidation = "not-applicable";
           } else {
             throw error;
           }
         }
       }
+
+      result = await applyResponseFinalizerHooks(
+        result,
+        true,
+        responseValidation,
+      );
+      finalResponse = normalizeHttpResponse(result.response);
+      finalError = result.error;
+      finalOwner = responseOwnerFor(finalResponse, result.owner);
+
       if (!isWebResponse(finalResponse)) {
         finalResponse = withFrameworkErrorOwnerHeader(
           finalResponse,
           finalOwner,
         );
       }
+      stages.sendMs = performance.now() - sendStartedAt;
 
       const durationMs = Date.now() - startedAt;
+      const stageTimings = roundStageTimings(stages);
       for (const hook of hooks) {
         if (!hook.afterSend) continue;
         try {
@@ -1921,6 +2091,7 @@ function createRequestExecutor<
             response: responseForHooks(finalResponse),
             error: finalError,
             durationMs,
+            stages: stageTimings,
           });
         } catch {
           // Ignore after-response hook failures; they should never change the response.
@@ -1976,6 +2147,12 @@ function buildHandler<
   routeHooks: readonly RouteHook<unknown, object>[] = [],
   optionsOverrides?: {
     skipRoutePreparation?: boolean;
+    /**
+     * Run the route through the full hook pipeline without contract
+     * preparation: no query/path/header/body parsing or validation, and the
+     * request body is left unconsumed for the handler.
+     */
+    rawRoute?: boolean;
   },
   responseValidationExemptStatus?: number,
 ): (
@@ -2491,6 +2668,24 @@ export async function createServer<
       const contract = resolveContract(contractLike);
       return createBuilder(contract, true);
     },
+    rawRoute: (init) => ({
+      handle: (fn) => {
+        const built = buildHandler(
+          options,
+          finalPorts,
+          contextRuntime,
+          rawRouteContract(init),
+          fn,
+          hooks,
+          [],
+          { rawRoute: true },
+        );
+        // The adapter owns routing for raw routes — the handler is mounted
+        // at its own path — so path/method matching is skipped and
+        // `init.path` stays identity for hooks and instrumentation.
+        return (req) => built(req, {});
+      },
+    }),
     createRequestContext: (req) => createRequestContext(req),
     createServiceContext,
     runServiceContext,
@@ -2500,6 +2695,32 @@ export async function createServer<
   };
 }
 
+function roundStageTimings(stages: RequestStageTimings): RequestStageTimings {
+  const round = (value: number) => Math.round(value * 100) / 100;
+  return {
+    onRequestMs: round(stages.onRequestMs),
+    parseMs: round(stages.parseMs),
+    contextMs: round(stages.contextMs),
+    beforeHandleMs: round(stages.beforeHandleMs),
+    handlerMs: round(stages.handlerMs),
+    sendMs: round(stages.sendMs),
+  };
+}
+
+function rawRouteContract(init: RawRouteInit): HttpContractConfig {
+  return {
+    kind: "http",
+    name: init.name,
+    method: init.method,
+    path: init.path,
+    pathParams: null,
+    query: null,
+    body: null,
+    responses: {},
+    metadata: init.metadata ?? {},
+  };
+}
+
 /**
  * Define and flatten route registrations with strong type inference.
  *