@beignet/core 0.0.26 → 0.0.28

package/src/server/hooks/rate-limit.ts

@@ -31,7 +31,9 @@ type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
 /**
  * Strategy for resolving the client IP used by `ip`-scoped limits.
  *
- * - `"none"` (default): do not trust request headers for IP resolution.
+ * - `"none"`: do not trust request headers for IP resolution. Every request
+ *   shares one `ip:unknown` bucket; this is the explicit opt-out for apps
+ *   that declare `ip` scopes without a trusted client-IP source.
  * - `"x-forwarded-for-last"`: the last `x-forwarded-for` entry. Use this only
  *   when the app is always behind a trusted reverse proxy that appends the
  *   socket address.
@@ -73,8 +75,11 @@ export interface RateLimitOptions<Ctx> {
   /**
    * Resolve the client IP for `ip`-scoped limits.
    *
-   * Defaults to `"none"`. Pass an explicit trusted proxy strategy or a
-   * function for platform-specific headers.
+   * There is no default: when any contract declares an `ip`-scoped rate limit
+   * and neither `ipSource` nor a custom `earlyKey` is configured, the hook
+   * fails at startup. Pass an explicit trusted proxy strategy, a function for
+   * platform-specific headers, or `"none"` to explicitly accept one shared
+   * `ip:unknown` bucket for all clients.
    */
   ipSource?: RateLimitIpSource;
 }
@@ -109,6 +114,20 @@ function resolveClientIp(
     : entries[entries.length - 1];
 }
 
+function formatContractNames(names: readonly string[]): string {
+  return names.map((name) => `"${name}"`).join(", ");
+}
+
+function ipSourceConfigurationError(contractNames: string): Error {
+  return new Error(
+    `createRateLimitHooks(...) has no ipSource configured, but contract(s) ${contractNames} declare an "ip"-scoped rate limit. ` +
+      `Set ipSource to "x-forwarded-for-last" (app is always behind a trusted reverse proxy that appends the socket address), ` +
+      `"x-forwarded-for-first" (a trusted edge normalizes the header before it reaches the app), ` +
+      `a function for platform-specific headers such as cf-connecting-ip, ` +
+      `or "none" to explicitly accept one shared ip:unknown bucket for all clients.`,
+  );
+}
+
 function emitUserKey(userId: string): string {
   return `user:${userId}`;
 }
@@ -210,10 +229,20 @@ async function enforceRateLimit(
  *
  * The hook reads `contract.metadata.rateLimit`. Global and IP-scoped limits run
  * in `onRequest` before context creation; user-scoped limits run in
- * `beforeHandle` after `ctx.actor` is available. Exceeded limits throw the
- * framework `TooManyRequests` app error with `scope`, `retryAfterSeconds`, and
- * `resetAt` details. The bucket key is never sent to clients; denials emit a
- * `rateLimit.denied` instrumentation event that carries the key for operators.
+ * `beforeHandle` after route hooks have resolved identity and `ctx.actor` is
+ * available. Exceeded limits throw the framework `TooManyRequests` app error
+ * with `scope`, `retryAfterSeconds`, and `resetAt` details. The bucket key is
+ * never sent to clients; denials emit a `rateLimit.denied` instrumentation
+ * event that carries the key for operators.
+ *
+ * `ip`-scoped limits require an explicit `ipSource` (or a custom `earlyKey`):
+ * the hook's `validate` phase fails `createServer(...)` startup when a
+ * registered contract declares an `ip` scope without one, instead of silently
+ * collapsing all clients into a shared `ip:unknown` bucket. Contracts added
+ * later through `server.route(...)` are not visible to `validate`, so
+ * enforcing an `ip`-scoped limit without an `ipSource` throws the same
+ * configuration error at request time as a backstop. Pass `ipSource: "none"`
+ * to explicitly opt in to the shared `ip:unknown` bucket.
  *
  * @param options - Optional key builders and client-IP source.
  * @returns A server hook backed by `ctx.ports.rateLimit`.
@@ -221,11 +250,31 @@ async function enforceRateLimit(
 export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
   options: RateLimitOptions<Ctx> = {},
 ): ServerHook<Ctx, RateLimitPorts> {
-  const ipSource = options.ipSource ?? "none";
-  const getClientIp = (req: HttpRequestLike) => resolveClientIp(req, ipSource);
+  const { ipSource } = options;
+  const getClientIp = (
+    req: HttpRequestLike,
+    contractName: string,
+  ): string | undefined => {
+    if (ipSource === undefined) {
+      throw ipSourceConfigurationError(formatContractNames([contractName]));
+    }
+    return resolveClientIp(req, ipSource);
+  };
 
   return {
     name: "rate-limit",
+    validate: ({ contracts }) => {
+      if (ipSource !== undefined || options.earlyKey) {
+        return;
+      }
+      const ipScoped = contracts
+        .filter((contract) => contract.metadata?.rateLimit?.scope === "ip")
+        .map((contract) => contract.name);
+      if (ipScoped.length === 0) {
+        return;
+      }
+      throw ipSourceConfigurationError(formatContractNames(ipScoped));
+    },
     onRequest: async ({ contract, ports, req }) => {
       const rlMeta = contract.metadata?.rateLimit;
       if (!rlMeta) {
@@ -239,7 +288,9 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
 
       const key =
         options.earlyKey?.({ req, scope }) ??
-        defaultEarlyRateLimitKey({ req, scope }, getClientIp);
+        defaultEarlyRateLimitKey({ req, scope }, (r) =>
+          getClientIp(r, contract.name),
+        );
 
       await enforceRateLimit(ports, {
         key,
@@ -263,7 +314,9 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
 
       const key =
         options.key?.({ ctx, req, scope }) ??
-        defaultRateLimitKey({ ctx, req, scope }, getClientIp);
+        defaultRateLimitKey({ ctx, req, scope }, (r) =>
+          getClientIp(r, contract.name),
+        );
 
       await enforceRateLimit(ctx.ports, {
         key,

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,22 +426,34 @@ 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> {
   /**
    * Optional name used in diagnostics and devtools.
    */
   name?: string;
+  /**
+   * Validates the hook configuration against the registered contracts.
+   *
+   * Invoked once at startup, right after `createServer(...)` collects the
+   * contracts from the `routes` option and before provider setup. Throw to
+   * fail startup instead of degrading silently at request time. Contracts
+   * registered later through `server.route(...)` are not seen here, so hooks
+   * that need full coverage should keep a runtime check as a backstop.
+   */
+  validate?: (args: { contracts: readonly HttpContractConfig[] }) => void;
   /**
    * Runs after route matching and before body/query/header parsing.
    */
   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];
+}

package/src/server/request-context.ts

@@ -44,6 +44,21 @@ export function clearActiveRequestContext(): void {
   activeRequestContext.enterWith(undefined);
 }
 
+/**
+ * Run a function inside a scoped ambient request context frame.
+ *
+ * Internal to the server runtime — not part of the public package surface.
+ * `server.runServiceContext(...)` uses this `AsyncLocalStorage.run` form
+ * instead of `enterWith` because resuming an `enterWith` frame across
+ * top-level await crashes Bun 1.3.x in plain scripts.
+ */
+export function runWithActiveRequestContext<T>(
+  context: ActiveRequestContext,
+  fn: () => T,
+): T {
+  return activeRequestContext.run(context, fn);
+}
+
 /**
  * Read the ambient request context, when one is active.
  */