@beignet/core 0.0.47 → 0.0.49

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/request-executor.ts

@@ -949,17 +949,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,
@@ -82,7 +83,10 @@ function requestValidationDetails(
     ...additionalDetails,
   };
 
-  if (error instanceof SchemaValidationError) {
+  if (
+    error instanceof SchemaValidationError ||
+    error instanceof QueryTransportError
+  ) {
     return {
       ...details,
       issues: error.issues,
@@ -282,17 +286,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/server.ts

@@ -807,6 +807,7 @@ export async function createServer<
     path,
     pathParams: null,
     query: null,
+    queryTransport: null,
     body: null,
     responses: {},
     metadata: {},
@@ -929,6 +930,7 @@ function rawRouteContract(init: RawRouteInit): HttpContractConfig {
     path: init.path,
     pathParams: null,
     query: null,
+    queryTransport: null,
     body: null,
     responses: {},
     metadata: init.metadata ?? {},

package/src/server/use-case-route.ts

@@ -192,8 +192,10 @@ type UseCaseRouteShape<
   /**
    * Map parsed request parts to the use case input.
    *
-   * Defaults to `defaultBinderInput`, which merges query, body, and path
-   * objects (path wins collisions) and never merges headers.
+   * A sole declared path, query, or body schema is passed through unchanged
+   * when no additional path, query, or object body values are present.
+   * Otherwise `defaultBinderInput` merges query, body, and path objects (path
+   * wins collisions) and never merges headers.
    */
   input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
   handle?: never;
@@ -330,9 +332,10 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * Merges parsed query, body, and path objects into one input object. Path
  * keys win all collisions, then body keys, then query keys. Headers are never
  * merged: parsed headers include every raw request header, so merging them
- * would poison the use case input. Non-object bodies (text, arrays, scalars)
- * are excluded. Routes that need headers or non-object bodies declare an
- * explicit `input` mapper.
+ * would poison the use case input. The route binder passes a sole declared
+ * input schema through unchanged when no other object input contains values;
+ * this merge handles every other default mapping. Routes that combine a
+ * non-object body with another source declare an explicit `input` mapper.
  */
 export function defaultBinderInput(parts: {
   path: unknown;
@@ -356,16 +359,42 @@ export function isUseCaseRouteDef(route: {
   return route.useCase !== undefined && route.useCase !== null;
 }
 
-function computeTrustedInput(
+function computeSingleInput(
   contract: HttpContractConfig,
   def: RuntimeUseCaseRouteDef,
-): boolean {
-  if (def.input) return false;
+): { source: "path" | "query" | "body"; schema: unknown } | undefined {
+  if (def.input) return undefined;
+
+  const sources = [
+    { source: "path", schema: contract.pathParams },
+    {
+      source: "query",
+      schema: contract.query,
+    },
+    {
+      source: "body",
+      schema: contract.body,
+    },
+  ] as const;
+  const present = sources.filter(
+    (candidate) => candidate.schema !== null && candidate.schema !== undefined,
+  );
+  const single = present[0];
+  return present.length === 1 && single
+    ? { source: single.source, schema: single.schema }
+    : undefined;
+}
 
-  const sources = [contract.pathParams, contract.query, contract.body].filter(
-    (schema) => schema !== null && schema !== undefined,
+function canPassSingleInput(
+  parts: { path: unknown; query: unknown; body: unknown },
+  source: "path" | "query" | "body",
+): boolean {
+  return (["path", "query", "body"] as const).every(
+    (candidate) =>
+      candidate === source ||
+      !isPlainObject(parts[candidate]) ||
+      Object.keys(parts[candidate]).length === 0,
   );
-  return sources.length === 1 && sources[0] === def.useCase.inputSchema;
 }
 
 function computeResponseExemption(
@@ -405,11 +434,11 @@ export function createUseCaseRouteHandler<Ctx, C extends HttpContractConfig>(
     );
   }
 
-  const mapInput = def.input ?? defaultBinderInput;
-  const trustedRun = computeTrustedInput(contract, def)
-    ? def.useCase[USE_CASE_TRUSTED_RUN_KEY]
-    : undefined;
-  const run = trustedRun ?? def.useCase.run;
+  const singleInput = computeSingleInput(contract, def);
+  const trustedRun =
+    singleInput?.schema === def.useCase.inputSchema
+      ? def.useCase[USE_CASE_TRUSTED_RUN_KEY]
+      : undefined;
 
   const handler: Handler<Ctx, C> = async ({
     ctx,
@@ -417,13 +446,23 @@ export function createUseCaseRouteHandler<Ctx, C extends HttpContractConfig>(
     query,
     headers,
     body,
-  }) => ({
-    status,
-    body: await run.call(def.useCase, {
-      ctx,
-      input: mapInput({ path, query, headers, body }),
-    }),
-  });
+  }) => {
+    const parts = { path, query, headers, body };
+    const passSingle =
+      singleInput !== undefined &&
+      canPassSingleInput(parts, singleInput.source);
+    const input = def.input
+      ? def.input(parts)
+      : passSingle
+        ? parts[singleInput.source]
+        : defaultBinderInput(parts);
+    const run = passSingle && trustedRun ? trustedRun : def.useCase.run;
+
+    return {
+      status,
+      body: await run.call(def.useCase, { ctx, input }),
+    };
+  };
 
   return {
     handler,

package/src/query-codec.ts

@@ -1,130 +0,0 @@
-const QUERY_VALUE_PREFIX = "~beignet-query:";
-
-type EncodedQueryValue =
-  | { type: "null" }
-  | { type: "string"; value: string }
-  | { type: "number"; value: number }
-  | { type: "boolean"; value: boolean }
-  | { type: "date"; value: string }
-  | { type: "array"; value: EncodedQueryValue[] }
-  | { type: "object"; value: Record<string, EncodedQueryValue> };
-
-function encodeStructuredValue(
-  value: unknown,
-  ancestors: Set<object>,
-): EncodedQueryValue {
-  if (value === null) return { type: "null" };
-  if (typeof value === "string") return { type: "string", value };
-  if (typeof value === "number" && Number.isFinite(value)) {
-    return { type: "number", value };
-  }
-  if (typeof value === "boolean") return { type: "boolean", value };
-  if (value instanceof Date && Number.isFinite(value.getTime())) {
-    return { type: "date", value: value.toISOString() };
-  }
-  if (typeof value !== "object" || value === null) {
-    throw new TypeError("Query value is not serializable.");
-  }
-  if (ancestors.has(value)) {
-    throw new TypeError("Query value contains a circular reference.");
-  }
-
-  ancestors.add(value);
-  try {
-    if (Array.isArray(value)) {
-      return {
-        type: "array",
-        value: value.map((entry) => encodeStructuredValue(entry, ancestors)),
-      };
-    }
-
-    const prototype = Object.getPrototypeOf(value);
-    if (prototype !== Object.prototype && prototype !== null) {
-      throw new TypeError("Query value contains a non-plain object.");
-    }
-    return {
-      type: "object",
-      value: Object.fromEntries(
-        Object.entries(value)
-          .filter(([, entry]) => entry !== undefined)
-          .map(([key, entry]) => [
-            key,
-            encodeStructuredValue(entry, ancestors),
-          ]),
-      ),
-    };
-  } finally {
-    ancestors.delete(value);
-  }
-}
-
-function decodeStructuredValue(value: unknown): unknown {
-  if (typeof value !== "object" || value === null || !("type" in value)) {
-    throw new TypeError("Invalid encoded query value.");
-  }
-  const encoded = value as { type: unknown; value?: unknown };
-
-  switch (encoded.type) {
-    case "null":
-      return null;
-    case "string":
-      if (typeof encoded.value === "string") return encoded.value;
-      break;
-    case "number":
-      if (typeof encoded.value === "number" && Number.isFinite(encoded.value)) {
-        return encoded.value;
-      }
-      break;
-    case "boolean":
-      if (typeof encoded.value === "boolean") return encoded.value;
-      break;
-    case "date": {
-      if (typeof encoded.value !== "string") break;
-      const date = new Date(encoded.value);
-      if (Number.isFinite(date.getTime())) return date;
-      break;
-    }
-    case "array":
-      if (Array.isArray(encoded.value)) {
-        return encoded.value.map(decodeStructuredValue);
-      }
-      break;
-    case "object":
-      if (
-        typeof encoded.value === "object" &&
-        encoded.value !== null &&
-        !Array.isArray(encoded.value)
-      ) {
-        return Object.fromEntries(
-          Object.entries(encoded.value).map(([key, entry]) => [
-            key,
-            decodeStructuredValue(entry),
-          ]),
-        );
-      }
-      break;
-  }
-
-  throw new TypeError("Invalid encoded query value.");
-}
-
-export function encodeQueryValue(value: unknown): string {
-  if (typeof value === "string" && !value.startsWith(QUERY_VALUE_PREFIX)) {
-    return value;
-  }
-  return `${QUERY_VALUE_PREFIX}${JSON.stringify(
-    encodeStructuredValue(value, new Set()),
-  )}`;
-}
-
-export function decodeQueryValue(value: string): unknown {
-  if (!value.startsWith(QUERY_VALUE_PREFIX)) return value;
-
-  try {
-    return decodeStructuredValue(
-      JSON.parse(value.slice(QUERY_VALUE_PREFIX.length)) as unknown,
-    );
-  } catch {
-    return value;
-  }
-}