@beignet/core 0.0.27 → 0.0.28

package/src/server/http.ts

@@ -340,6 +340,26 @@ export type BeforeSendHook<
   native?: boolean;
 }) => MaybePromise<HttpResponseLike | undefined>;
 
+/**
+ * Per-stage timing breakdown of one request, in milliseconds.
+ *
+ * Stages are measured around the pipeline phases in execution order:
+ * `onRequest` hooks, request parsing/validation, context creation, route
+ * hooks plus `beforeHandle` hooks, the route handler, and response
+ * preparation (`beforeSend`, response validation, and finalizers). Stages
+ * that did not run for a request — parsing on raw routes, the handler after
+ * a hook short-circuit — report `0`. The stages do not sum exactly to the
+ * request `durationMs`; routing and bookkeeping live in the gaps.
+ */
+export type RequestStageTimings = {
+  onRequestMs: number;
+  parseMs: number;
+  contextMs: number;
+  beforeHandleMs: number;
+  handlerMs: number;
+  sendMs: number;
+};
+
 /**
  * Hook that runs after the response has been prepared.
  *
@@ -360,6 +380,10 @@ export type AfterSendHook<
   response: HttpResponseLike;
   error?: unknown;
   durationMs: number;
+  /**
+   * Per-stage timing breakdown of this request.
+   */
+  stages: RequestStageTimings;
 }) => MaybePromise<void>;
 
 /**
@@ -402,10 +426,12 @@ export type ServerUnhandledErrorMapper<
 /**
  * Server lifecycle hook collection.
  *
- * Hooks run in the order they are registered. `onRequest` can short-circuit
- * before context creation; `beforeHandle` can replace context or short-circuit;
- * `beforeSend` can replace the outgoing response; `afterSend` observes the
- * final response.
+ * Hooks run in the order they are registered within each server-hook phase.
+ * `onRequest` can short-circuit before context creation; route hooks resolve
+ * route-scoped context before server `beforeHandle`; `beforeHandle` can replace
+ * context or short-circuit; `beforeSend` can replace the outgoing response, and
+ * route-owned replacements are contract-validated before send; `afterSend`
+ * observes the final response.
  */
 export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
   /**
@@ -427,7 +453,7 @@ export interface ServerHook<Ctx, Ports extends AnyPorts = AnyPorts> {
    */
   onRequest?: OnRequestHook<Ports>;
   /**
-   * Runs after request parsing and context creation.
+   * Runs after request parsing, context creation, and route hook resolution.
    */
   beforeHandle?: BeforeHandleHook<Ctx>;
   /**

package/src/server/index.ts

@@ -69,6 +69,8 @@ export {
 export type {
   CreateServerOptions,
   HandlerRouteDef,
+  RawRouteBuilder,
+  RawRouteInit,
   RouteDef,
   RouteGroup,
   ServerInstance,

package/src/server/instrumentation.ts

@@ -371,7 +371,15 @@ export function createServerInstrumentation<Ctx>(
         },
       };
     },
-    afterSend: ({ req, ctx, contract, response, error, durationMs }) => {
+    afterSend: ({
+      req,
+      ctx,
+      contract,
+      response,
+      error,
+      durationMs,
+      stages,
+    }) => {
       try {
         if (!port) return;
 
@@ -414,6 +422,7 @@ export function createServerInstrumentation<Ctx>(
             responseOwner,
             status: response.status,
             durationMs,
+            stages,
             details: {
               headers: requestHeadersToRecord(req.headers),
               route: {

package/src/server/internal-hooks.ts

@@ -0,0 +1,49 @@
+import type { HttpContractConfig } from "../contracts/index.js";
+import type {
+  HttpRequestLike,
+  HttpResponseLike,
+  MaybePromise,
+} from "./http.js";
+
+export const responseFinalizerHook = Symbol(
+  "@beignet/core/server/responseFinalizer",
+);
+
+export type ResponseFinalizerResponseOwner =
+  | "route"
+  | "framework"
+  | "transport";
+
+export type ResponseFinalizerValidationState =
+  | "validated"
+  | "disabled"
+  | "not-applicable";
+
+export type ResponseFinalizerHookArgs<Ctx> = {
+  req: HttpRequestLike;
+  ctx?: Ctx;
+  contract: HttpContractConfig;
+  path?: unknown;
+  query?: unknown;
+  headers?: unknown;
+  body?: unknown;
+  response: HttpResponseLike;
+  error?: unknown;
+  native?: boolean;
+  owner: ResponseFinalizerResponseOwner;
+  responseValidation: ResponseFinalizerValidationState;
+};
+
+export type ResponseFinalizerHook<Ctx> = (
+  args: ResponseFinalizerHookArgs<Ctx>,
+) => MaybePromise<void>;
+
+export type ResponseFinalizerServerHook<Ctx> = {
+  [responseFinalizerHook]?: ResponseFinalizerHook<Ctx>;
+};
+
+export function getResponseFinalizerHook<Ctx>(
+  hook: unknown,
+): ResponseFinalizerHook<Ctx> | undefined {
+  return (hook as ResponseFinalizerServerHook<Ctx>)[responseFinalizerHook];
+}