@beignet/core 0.0.48 → 0.0.50

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

@@ -4,7 +4,11 @@
 
 import type { RateLimitScope } from "../../contracts/index.js";
 import { AppError, httpErrors } from "../../errors/index.js";
-import type { ActivityActor, RateLimitPort } from "../../ports/index.js";
+import {
+  type ActivityActor,
+  AuthUnauthorizedError,
+  type RateLimitPort,
+} from "../../ports/index.js";
 import {
   createProviderInstrumentation,
   type ProviderInstrumentationTarget,
@@ -38,8 +42,9 @@ type EarlyRateLimitScope = Exclude<RateLimitScope, "user">;
  * Strategy for resolving the client IP used by `ip`-scoped limits.
  *
  * - `"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.
+ *   to one contract shares that contract's unknown-client 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.
@@ -59,7 +64,9 @@ export interface RateLimitOptions<Ctx> {
   /**
    * Build a rate-limit key after context exists.
    *
-   * This is used for user-scoped limits and any late key strategy.
+   * This is used for user-scoped limits and any late key strategy. The
+   * returned value is the complete key and is not automatically namespaced by
+   * contract.
    */
   key?: (args: {
     ctx: Ctx;
@@ -69,7 +76,8 @@ export interface RateLimitOptions<Ctx> {
   /**
    * Build a rate-limit key before request parsing and context creation.
    *
-   * This is used for global and IP-scoped limits.
+   * This is used for global and IP-scoped limits. The returned value is the
+   * complete key and is not automatically namespaced by contract.
    */
   earlyKey?: (args: {
     req: HttpRequestLike;
@@ -124,16 +132,23 @@ function ipSourceConfigurationError(contractNames: string): Error {
     `createRateLimitHooks(...) has no client IP source configured, but contract(s) ${contractNames} declare an "ip"-scoped rate limit. ` +
       `Set trustedProxy.clientIp or ipSource to a header source written by a trusted edge, ` +
       `for example "x-forwarded-for-last", "x-forwarded-for-first", "x-real-ip", "cf-connecting-ip", or a custom function, ` +
-      `or "none" to explicitly accept one shared ip:unknown bucket for all clients.`,
+      `or "none" to explicitly accept one shared unknown-client bucket per contract.`,
   );
 }
 
-function emitUserKey(userId: string): string {
-  return `user:${userId}`;
+function namespaceContractKey(contractName: string, key: string): string {
+  const encodedContractName = contractName
+    .replaceAll("%", "%25")
+    .replaceAll(":", "%3A");
+  return `contract:${encodedContractName}:${key}`;
+}
+
+function emitUserKey(contractName: string, userId: string): string {
+  return namespaceContractKey(contractName, `user:${userId}`);
 }
 
-function emitIpKey(ip: string): string {
-  return `ip:${ip}`;
+function emitIpKey(contractName: string, ip: string): string {
+  return namespaceContractKey(contractName, `ip:${ip}`);
 }
 
 function defaultRateLimitKey<Ctx extends CtxWithRateLimit>(
@@ -141,36 +156,41 @@ function defaultRateLimitKey<Ctx extends CtxWithRateLimit>(
     ctx: Ctx;
     req: HttpRequestLike;
     scope: RateLimitScope;
+    contractName: string;
   },
   getClientIp: (req: HttpRequestLike) => string | undefined,
 ): string {
-  const { ctx, req, scope } = args;
+  const { contractName, ctx, req, scope } = args;
 
-  if (scope === "user" && ctx.actor?.type === "user" && ctx.actor.id) {
-    return emitUserKey(ctx.actor.id);
+  if (scope === "user") {
+    if (ctx.actor?.type !== "user" || !ctx.actor.id) {
+      throw new AuthUnauthorizedError();
+    }
+    return emitUserKey(contractName, ctx.actor.id);
   }
 
   if (scope === "ip") {
     const ip = getClientIp(req) || "unknown";
-    return emitIpKey(ip);
+    return emitIpKey(contractName, ip);
   }
 
-  return "global";
+  return namespaceContractKey(contractName, "global");
 }
 
 function defaultEarlyRateLimitKey(
   args: {
     req: HttpRequestLike;
     scope: EarlyRateLimitScope;
+    contractName: string;
   },
   getClientIp: (req: HttpRequestLike) => string | undefined,
 ): string {
   if (args.scope === "ip") {
     const ip = getClientIp(args.req) || "unknown";
-    return emitIpKey(ip);
+    return emitIpKey(args.contractName, ip);
   }
 
-  return "global";
+  return namespaceContractKey(args.contractName, "global");
 }
 
 async function enforceRateLimit(
@@ -233,7 +253,10 @@ 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 route hooks have resolved identity and `ctx.actor` is
- * available. Exceeded limits throw the framework `TooManyRequests` app error
+ * available. Default keys include the contract name so unrelated contracts do
+ * not share counters. A user-scoped limit without a resolved user actor fails
+ * with `AuthUnauthorizedError` instead of falling back to a global bucket.
+ * Exceeded limits throw the framework `TooManyRequests` app error
  * with `scope`, `retryAfterSeconds`, and `resetAt` details, and the 429
  * response carries a `Retry-After` header when the limiter reports a reset
  * time. The bucket key is
@@ -243,11 +266,12 @@ async function enforceRateLimit(
  * `ip`-scoped limits require an explicit `trustedProxy.clientIp`, `ipSource`,
  * or 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.
+ * instead of silently collapsing all clients into one shared bucket.
  * Contracts added later through `server.route(...)` are not visible to
  * `validate`, so enforcing an `ip`-scoped limit without a client-IP source
  * throws the same configuration error at request time as a backstop. Pass
- * `ipSource: "none"` to explicitly opt in to the shared `ip:unknown` bucket.
+ * `ipSource: "none"` to explicitly opt in to one unknown-client bucket per
+ * contract.
  *
  * @param options - Optional key builders and client-IP source.
  * @returns A server hook backed by `ctx.ports.rateLimit`.
@@ -309,8 +333,9 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
 
       const key =
         options.earlyKey?.({ req, scope }) ??
-        defaultEarlyRateLimitKey({ req, scope }, (r) =>
-          getClientIp(r, requestInfo, contract.name),
+        defaultEarlyRateLimitKey(
+          { req, scope, contractName: contract.name },
+          (r) => getClientIp(r, requestInfo, contract.name),
         );
 
       await enforceRateLimit(ports, {
@@ -335,8 +360,9 @@ export function createRateLimitHooks<Ctx extends CtxWithRateLimit>(
 
       const key =
         options.key?.({ ctx, req, scope }) ??
-        defaultRateLimitKey({ ctx, req, scope }, (r) =>
-          getClientIp(r, requestInfo, contract.name),
+        defaultRateLimitKey(
+          { ctx, req, scope, contractName: contract.name },
+          (r) => getClientIp(r, requestInfo, contract.name),
         );
 
       await enforceRateLimit(ctx.ports, {

package/src/server/hooks/security.ts

@@ -9,7 +9,11 @@ import {
   type TrustedProxyConfig,
   type TrustedProxyOptions,
 } from "../trusted-proxy.js";
-import type { HttpRequestLike, ServerHook } from "../types.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  ServerHook,
+} from "../types.js";
 
 /**
  * Strict-Transport-Security configuration.
@@ -180,7 +184,7 @@ const DEFAULT_CSRF_HEADER = "x-csrf-token";
 const DEFAULT_CSRF_COOKIE = "beignet.csrf";
 
 function headerKey(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
 ): string | undefined {
   const lowerName = name.toLowerCase();
@@ -188,7 +192,7 @@ function headerKey(
 }
 
 function setHeaderIfMissing(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
   value: string | false | undefined,
 ): void {
@@ -217,7 +221,7 @@ function formatStrictTransportSecurity(
  * provide more specific policies.
  */
 export function applySecurityHeaders(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   options: SecurityHeadersOptions = {},
 ): void {
   setHeaderIfMissing(

package/src/server/http.ts

@@ -29,6 +29,14 @@ export interface HttpRequestLike {
    * Request headers.
    */
   headers: Headers;
+  /**
+   * Abort signal for the request lifecycle when the platform exposes one.
+   *
+   * Streaming handlers should pass this to resources that must close when
+   * the client disconnects. Adapters without cancellation support may omit
+   * it.
+   */
+  signal?: AbortSignal;
   /**
    * The platform request when an adapter has one available.
    *
@@ -62,6 +70,19 @@ export interface HttpRequestLike {
   clone?(): HttpRequestLike;
 }
 
+/**
+ * Header values accepted by a framework-neutral Beignet response.
+ *
+ * Use an array when the field must be emitted more than once, such as
+ * `Set-Cookie`. Adapters append every array item as a separate field value.
+ */
+export type HttpResponseHeaderValue = string | readonly string[];
+
+/**
+ * Framework-neutral response headers.
+ */
+export type HttpResponseHeaders = Record<string, HttpResponseHeaderValue>;
+
 /**
  * Framework-neutral response object returned by route handlers and hooks.
  */
@@ -71,9 +92,9 @@ export interface HttpResponseLike {
    */
   status: number;
   /**
-   * Response headers.
+   * Response headers. Array values are emitted as repeated header fields.
    */
-  headers?: Record<string, string>;
+  headers?: HttpResponseHeaders;
   /**
    * JSON-serializable body or an adapter-specific body value.
    */

package/src/server/index.ts

@@ -95,6 +95,10 @@ export {
  * Server context blueprint declaration helper.
  */
 export { defineServerContext } from "./server-context.js";
+/**
+ * Portable Server-Sent Events response helper.
+ */
+export * from "./server-sent-events.js";
 /**
  * Trusted proxy request metadata helpers.
  */

package/src/server/instrumentation.ts

@@ -16,7 +16,12 @@ import {
   type TraceContext,
   type TracingPort,
 } from "../tracing/index.js";
-import type { HttpRequestLike, HttpResponseLike, ServerHook } from "./http.js";
+import type {
+  HttpRequestLike,
+  HttpResponseHeaders,
+  HttpResponseLike,
+  ServerHook,
+} from "./http.js";
 import {
   clearActiveRequestContext,
   enterActiveRequestContext,
@@ -205,17 +210,20 @@ function requestHeadersToRecord(headers: Headers): Record<string, string> {
 }
 
 function getResponseHeader(
-  headers: Record<string, string> | undefined,
+  headers: HttpResponseHeaders | undefined,
   name: string,
 ): string | undefined {
   if (!headers) return undefined;
   const direct = headers[name];
-  if (direct !== undefined) return direct;
+  if (direct !== undefined) {
+    return typeof direct === "string" ? direct : direct[0];
+  }
   const normalized = name.toLowerCase();
   const entry = Object.entries(headers).find(
     ([key]) => key.toLowerCase() === normalized,
   );
-  return entry?.[1];
+  const value = entry?.[1];
+  return typeof value === "string" ? value : value?.[0];
 }
 
 function getResponseOwner(

package/src/server/request-executor.ts

@@ -82,6 +82,7 @@ import {
   PathDecodeError,
 } from "./route-matching.js";
 import type { TrustedRequestInfo } from "./trusted-proxy.js";
+import { InvalidRequestUrlError } from "./trusted-proxy-internal.js";
 
 function withoutHeadResponseBody(
   response: HttpResponse,
@@ -281,6 +282,19 @@ export function createRequestExecutor<
         };
       }
 
+      if (currentError instanceof InvalidRequestUrlError) {
+        return {
+          ctx,
+          response: errorResponse(
+            400,
+            "INVALID_REQUEST_URL",
+            "Malformed request URL",
+          ),
+          error: currentError,
+          owner: "framework",
+        };
+      }
+
       if (isAppError(currentError)) {
         return {
           ctx,
@@ -949,17 +963,25 @@ export function createRequestExecutor<
               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 resolveErrorResult(
+              error,
+              result.ctx,
+              pathValue,
+              queryValue,
+              headersValue,
+              bodyValue,
+              { 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";
         }
       }
 

package/src/server/request-preparation.ts

@@ -1,10 +1,11 @@
 import {
+  decodeQueryTransport,
   getContractHeaderSchemas,
   type HttpContractConfig,
   methodSupportsRequestBody,
+  QueryTransportError,
   type StandardSchema,
 } from "../contracts/index.js";
-import { decodeQueryValue } from "../query-codec.js";
 import type { HttpRequestLike, HttpResponseLike } from "./http.js";
 import {
   parseStandardSchema,
@@ -40,6 +41,17 @@ type RequestValidationLocation = "query" | "path" | "headers" | "body";
 
 const DEFAULT_REQUEST_BODY_MAX_BYTES = 1024 * 1024;
 
+function cancelRequestBody(
+  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 413 response.
+  }
+}
+
 class RequestBodyTooLargeError extends Error {
   readonly maxBytes: number;
   readonly actualBytes?: number;
@@ -82,7 +94,10 @@ function requestValidationDetails(
     ...additionalDetails,
   };
 
-  if (error instanceof SchemaValidationError) {
+  if (
+    error instanceof SchemaValidationError ||
+    error instanceof QueryTransportError
+  ) {
     return {
       ...details,
       issues: error.issues,
@@ -204,9 +219,16 @@ async function readLimitedRequestText(
   req: HttpRequestLike,
   maxBytes: number,
 ): Promise<string> {
-  assertContentLengthWithinLimit(req.headers, maxBytes);
-
   const body = req.raw?.body;
+  try {
+    assertContentLengthWithinLimit(req.headers, maxBytes);
+  } catch (error) {
+    if (body) {
+      cancelRequestBody(body, error);
+    }
+    throw error;
+  }
+
   if (!body) {
     const text = await req.text();
     const actualBytes = new TextEncoder().encode(text).byteLength;
@@ -227,7 +249,9 @@ async function readLimitedRequestText(
       if (result.done) break;
       received += result.value.byteLength;
       if (received > maxBytes) {
-        throw new RequestBodyTooLargeError(maxBytes, received);
+        const error = new RequestBodyTooLargeError(maxBytes, received);
+        cancelRequestBody(reader, error);
+        throw error;
       }
       text += decoder.decode(result.value, { stream: true });
     }
@@ -282,17 +306,26 @@ export async function prepareRequestInputs(args: {
     maxRequestBodyBytes,
     rawRoute,
   } = args;
-  const rawQuery: Record<string, unknown> = {};
-  for (const key of new Set(url.searchParams.keys())) {
-    const values = url.searchParams.getAll(key);
-    const decoded = values.map(decodeQueryValue);
-    rawQuery[key] = decoded.length === 1 ? decoded[0] : decoded;
-  }
+  const rawQuery = Object.fromEntries(
+    [...new Set(url.searchParams.keys())].map((key) => {
+      const values = url.searchParams.getAll(key);
+      return [key, values.length === 1 ? values[0] : values];
+    }),
+  );
 
   let query: unknown = rawQuery;
   if (contract.query) {
+    if (!contract.queryTransport) {
+      throw new Error(
+        `Contract "${contract.name}" declares a query schema without a query transport.`,
+      );
+    }
     try {
-      query = await parseStandardSchema(contract.query, query);
+      const decoded = decodeQueryTransport(
+        contract.queryTransport,
+        url.searchParams,
+      );
+      query = await parseStandardSchema(contract.query, decoded);
     } catch (error) {
       return {
         ok: false,

package/src/server/response-finalization.ts

@@ -9,7 +9,11 @@ import {
   isErrorResponseBody,
 } from "../errors/index.js";
 import { getRequestIdFromContext } from "./hooks/utils.js";
-import type { HttpResponse, HttpResponseLike } from "./http.js";
+import type {
+  HttpResponse,
+  HttpResponseHeaders,
+  HttpResponseLike,
+} from "./http.js";
 import type { ResponseFinalizerResponseOwner } from "./internal-hooks.js";
 import {
   parseStandardSchema,
@@ -76,7 +80,7 @@ export function withFrameworkErrorOwnerHeader(
 }
 
 function setRecordHeader(
-  headers: Record<string, string>,
+  headers: HttpResponseHeaders,
   name: string,
   value: string,
 ): void {
@@ -89,6 +93,34 @@ function setRecordHeader(
   headers[name] = value;
 }
 
+function headerValues(value: string | readonly string[]): readonly string[] {
+  return typeof value === "string" ? [value] : value;
+}
+
+function sameHeaderValue(
+  left: string | readonly string[] | undefined,
+  right: string | readonly string[],
+): boolean {
+  if (left === undefined) return false;
+  const leftValues = headerValues(left);
+  const rightValues = headerValues(right);
+  return (
+    leftValues.length === rightValues.length &&
+    leftValues.every((value, index) => value === rightValues[index])
+  );
+}
+
+function appendHeaderValues(
+  headers: Headers,
+  name: string,
+  value: string | readonly string[],
+): void {
+  headers.delete(name);
+  for (const item of headerValues(value)) {
+    headers.append(name, item);
+  }
+}
+
 /** Apply contract-owned deprecation headers to any response representation. */
 export function withContractLifecycleHeaders(
   res: HttpResponse,
@@ -113,17 +145,18 @@ export function withContractLifecycleHeaders(
     });
   }
 
-  const headers = { ...(res.headers ?? {}) };
+  const headers: HttpResponseHeaders = { ...(res.headers ?? {}) };
   for (const [name, value] of Object.entries(lifecycleHeaders)) {
     if (name.toLowerCase() === "link") {
       const existingName = Object.keys(headers).find(
         (key) => key.toLowerCase() === "link",
       );
       const existing = existingName ? headers[existingName] : undefined;
+      const existingValue = existing ? headerValues(existing).join(", ") : "";
       setRecordHeader(
         headers,
         name,
-        existing ? `${existing}, ${value}` : value,
+        existingValue ? `${existingValue}, ${value}` : value,
       );
     } else {
       setRecordHeader(headers, name, value);
@@ -140,11 +173,18 @@ export function responseOwnerFor(
   return owner ?? "route";
 }
 
-function headersToRecord(headers: Headers): Record<string, string> {
-  const record: Record<string, string> = {};
+function headersToRecord(headers: Headers): HttpResponseHeaders {
+  const record: HttpResponseHeaders = {};
   headers.forEach((value, key) => {
     record[key] = value;
   });
+  const setCookies =
+    (headers as Headers & { getSetCookie?: () => string[] }).getSetCookie?.call(
+      headers,
+    ) ?? [];
+  if (setCookies.length > 0) {
+    record["set-cookie"] = setCookies;
+  }
   return record;
 }
 
@@ -169,10 +209,10 @@ export function responseForHooks(res: HttpResponse): HttpResponseLike {
  */
 export function mergeNativeResponseHeaders(
   nativeResponse: Response,
-  originalHeaders: Record<string, string>,
-  finalHeaders: Record<string, string>,
+  originalHeaders: HttpResponseHeaders,
+  finalHeaders: HttpResponseHeaders,
 ): Response {
-  const originalByLowerKey = new Map<string, string>();
+  const originalByLowerKey = new Map<string, string | readonly string[]>();
   for (const [key, value] of Object.entries(originalHeaders)) {
     originalByLowerKey.set(key.toLowerCase(), value);
   }
@@ -181,13 +221,9 @@ export function mergeNativeResponseHeaders(
   const merged = new Headers(nativeResponse.headers);
   for (const [key, value] of Object.entries(finalHeaders)) {
     const lowerKey = key.toLowerCase();
-    if (originalByLowerKey.get(lowerKey) === value) continue;
+    if (sameHeaderValue(originalByLowerKey.get(lowerKey), value)) continue;
     changed = true;
-    if (lowerKey === "set-cookie") {
-      merged.append(lowerKey, value);
-    } else {
-      merged.set(key, value);
-    }
+    appendHeaderValues(merged, key, value);
   }
 
   if (!changed) {

package/src/server/route-matching.ts

@@ -15,12 +15,35 @@ export class PathDecodeError extends Error {
   }
 }
 
+function encodeStaticSegment(value: string): string {
+  return encodeURI(value).replace(
+    /[?#]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+function matchPercentEncodingCase(value: string): string {
+  return value.replace(/%([0-9A-F]{2})/g, (_match, encoded: string) => {
+    const digits = [...encoded]
+      .map((digit) =>
+        /[A-F]/.test(digit) ? `[${digit}${digit.toLowerCase()}]` : digit,
+      )
+      .join("");
+    return `%${digits}`;
+  });
+}
+
 export function compilePath(path: string): CompiledPath {
   const parsed = parsePathTemplate(path);
   const regexParts = parsed.segments.map((segment) =>
     segment.kind === "dynamic"
       ? "([^/]+)"
-      : segment.value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+      : matchPercentEncodingCase(
+          encodeStaticSegment(segment.value).replace(
+            /[.*+?^${}()|[\]\\]/g,
+            "\\$&",
+          ),
+        ),
   );
   const pattern = new RegExp(`^/${regexParts.join("/")}$`);
   return { ...parsed, pattern };