@beignet/core 0.0.48 → 0.0.49

package/src/contracts/schema-shape.ts

@@ -73,3 +73,27 @@ export function formatPathParamsMismatch(args: {
     .filter(Boolean)
     .join("; ");
 }
+
+/** Compare an introspected query schema's fields with its transport fields. */
+export function compareQueryTransportFields(args: {
+  schemaKeys: readonly string[];
+  transportKeys: readonly string[];
+}): boolean {
+  const schemaKeys = [...args.schemaKeys].sort();
+  const transportKeys = [...args.transportKeys].sort();
+  return (
+    schemaKeys.length === transportKeys.length &&
+    schemaKeys.every((key, index) => key === transportKeys[index])
+  );
+}
+
+/** Format a query schema/transport mismatch consistently across consumers. */
+export function formatQueryTransportMismatch(args: {
+  contractName: string;
+  schemaKeys: readonly string[];
+  transportKeys: readonly string[];
+}): string {
+  const schemaKeys = [...args.schemaKeys].sort();
+  const transportKeys = [...args.transportKeys].sort();
+  return `Query transport fields for contract "${args.contractName}" must match its query schema fields (schema: ${schemaKeys.join(", ") || "none"}; transport: ${transportKeys.join(", ") || "none"}).`;
+}

package/src/contracts/types.ts

@@ -2,6 +2,7 @@ import type { StandardSchemaV1 } from "@standard-schema/spec";
 import type { IdempotencyMeta } from "../idempotency/index.js";
 import type { ContractDeprecationMeta } from "./lifecycle.js";
 import type { OpenAPIOperationMeta } from "./openapi-meta.js";
+import type { QueryTransport } from "./query-transport.js";
 import type { RateLimitMeta } from "./rate-limit.js";
 
 /**
@@ -343,6 +344,10 @@ export type HttpContractConfig<
    * Query parameter schema.
    */
   query: TQuery;
+  /**
+   * Deterministic HTTP encoding for the query schema.
+   */
+  queryTransport: QueryTransport | null;
   /**
    * Request header schema or schemas.
    */

package/src/openapi/index.ts

@@ -11,6 +11,8 @@ import {
   getContractHeaderSchemas,
   methodSupportsRequestBody,
   parsePathTemplate,
+  type QueryFieldTransport,
+  queryTransportSchema,
   resolveContract,
   STANDARD_ERROR_RESPONSE_SCHEMA,
 } from "../contracts/index.js";
@@ -20,7 +22,9 @@ import {
 } from "../contracts/lifecycle.js";
 import {
   comparePathParamsToTemplate,
+  compareQueryTransportFields,
   formatPathParamsMismatch,
+  formatQueryTransportMismatch,
 } from "../contracts/schema-shape.js";
 import {
   createZodIntrospector,
@@ -157,6 +161,21 @@ export interface ParameterObject {
    * Parameter schema.
    */
   schema?: SchemaObject | ReferenceObject;
+  /**
+   * OpenAPI parameter serialization style.
+   */
+  style?:
+    | "form"
+    | "simple"
+    | "matrix"
+    | "label"
+    | "spaceDelimited"
+    | "pipeDelimited"
+    | "deepObject";
+  /**
+   * Whether arrays and objects are expanded into separate parameter values.
+   */
+  explode?: boolean;
   /**
    * Parameter description.
    */
@@ -627,12 +646,36 @@ function addQueryParams(
   state: GeneratorState,
 ): void {
   if (!contract.query) return;
+  const transport = contract.queryTransport;
+  if (!transport) {
+    throw new Error(
+      `Contract "${contract.name}" declares a query schema without a query transport.`,
+    );
+  }
 
   const shape = state.introspector.getShape(contract.query);
-  if (!shape) return;
+  if (!shape) {
+    throw new Error(
+      `Unable to inspect query schema for contract "${contract.name}". Pass a schemaIntrospector that can read its fields so OpenAPI requiredness and constraints remain aligned with the declared query transport.`,
+    );
+  }
 
-  for (const key of Object.keys(shape)) {
+  const schemaKeys = Object.keys(shape);
+  const transportKeys = Object.keys(transport.fields);
+  if (!compareQueryTransportFields({ schemaKeys, transportKeys })) {
+    throw new Error(
+      formatQueryTransportMismatch({
+        contractName: contract.name,
+        schemaKeys,
+        transportKeys,
+      }),
+    );
+  }
+
+  for (const key of Object.keys(transport.fields)) {
     const originalField = shape[key];
+    const fieldTransport = transport.fields[key];
+    if (!originalField || !fieldTransport) continue;
     const optional = state.introspector.isOptional(originalField);
 
     const field = originalField;
@@ -644,6 +687,7 @@ function addQueryParams(
       state,
       "input",
     );
+    applyQueryTransportSchema(paramSchemaRef, fieldTransport, state);
 
     const param: ParameterObject = {
       name: key,
@@ -651,12 +695,92 @@ function addQueryParams(
       required: !optional,
       schema: paramSchemaRef,
       description,
+      style: fieldTransport.kind === "deep-object" ? "deepObject" : "form",
+      explode: true,
     };
 
     addParameter(operation, param);
   }
 }
 
+function applyQueryTransportSchema(
+  schema: SchemaObject | ReferenceObject,
+  transport: QueryFieldTransport,
+  state: GeneratorState,
+): void {
+  if (!("$ref" in schema) || typeof schema.$ref !== "string") return;
+  const prefix = "#/components/schemas/";
+  if (!schema.$ref.startsWith(prefix)) return;
+  const name = schema.$ref.slice(prefix.length);
+  const converted = state.components.schemas?.[name];
+  if (!converted || !state.components.schemas) return;
+  state.components.schemas[name] = mergeQueryTransportSchema(
+    converted,
+    transport,
+  );
+}
+
+function mergeQueryTransportSchema(
+  converted: SchemaObject,
+  transport: QueryFieldTransport,
+): SchemaObject {
+  const declared = queryTransportSchema(transport);
+  const merged: SchemaObject = {
+    ...converted,
+    type: declared.type,
+  };
+  if (declared.format) merged.format = declared.format;
+  if (transport.kind === "integer") {
+    merged.minimum = Math.max(
+      typeof converted.minimum === "number"
+        ? converted.minimum
+        : Number.MIN_SAFE_INTEGER,
+      Number.MIN_SAFE_INTEGER,
+    );
+    merged.maximum = Math.min(
+      typeof converted.maximum === "number"
+        ? converted.maximum
+        : Number.MAX_SAFE_INTEGER,
+      Number.MAX_SAFE_INTEGER,
+    );
+  }
+  if (declared["x-beignet-empty-query"]) {
+    merged["x-beignet-empty-query"] = declared["x-beignet-empty-query"];
+  }
+
+  if (transport.kind === "array") {
+    const convertedItems =
+      typeof converted.items === "object" && converted.items !== null
+        ? (converted.items as SchemaObject)
+        : {};
+    merged.items = mergeQueryTransportSchema(convertedItems, transport.item);
+  }
+
+  if (transport.kind === "deep-object") {
+    const convertedProperties =
+      typeof converted.properties === "object" && converted.properties !== null
+        ? (converted.properties as Record<string, unknown>)
+        : {};
+    merged.properties = Object.fromEntries(
+      Object.entries(transport.fields).map(([key, field]) => {
+        const convertedProperty = convertedProperties[key];
+        return [
+          key,
+          mergeQueryTransportSchema(
+            typeof convertedProperty === "object" && convertedProperty !== null
+              ? (convertedProperty as SchemaObject)
+              : {},
+            field,
+          ),
+        ];
+      }),
+    );
+    merged.additionalProperties = false;
+  }
+
+  return merged;
+}
+
 /**
  * Add header parameters from contract to operation.
  */

package/src/outbox/index.ts

@@ -555,7 +555,8 @@ export interface DrainOutboxOptions {
    */
   registry: OutboxRegistry;
   /**
-   * Event bus used for event messages.
+   * Event bus used for event messages. Required when the registry contains
+   * events.
    */
   eventBus?: {
     publish<E extends EventPayloadDef>(
@@ -565,7 +566,8 @@ export interface DrainOutboxOptions {
     ): MaybePromise<void>;
   };
   /**
-   * Job dispatcher used for job messages.
+   * Job dispatcher used for job messages. Required when the registry contains
+   * jobs.
    */
   jobs?: JobDispatcherPort;
   /**
@@ -1476,15 +1478,17 @@ async function deliverOutboxMessage(
  * Claim and deliver one batch of outbox messages.
  *
  * This does not loop forever; production workers should call it on their own
- * polling cadence. Event and job messages require matching registry entries.
- * Failed messages are retried with backoff until `maxAttempts`, then
- * dead-lettered.
+ * polling cadence. Event and job messages require matching registry entries
+ * and delivery transports. Required transports are validated before a batch
+ * is claimed. Failed messages are retried with backoff until `maxAttempts`,
+ * then dead-lettered.
  */
 export async function drainOutbox(
   options: DrainOutboxOptions,
 ): Promise<DrainOutboxResult> {
   const batchSize = options.batchSize ?? 100;
   assertPositiveInteger("batchSize", batchSize);
+  assertOutboxDeliveryCapabilities(options);
   const instrumentation = createProviderInstrumentation(
     options.instrumentation,
     {
@@ -1659,6 +1663,23 @@ export async function drainOutbox(
   return result;
 }
 
+function assertOutboxDeliveryCapabilities(options: DrainOutboxOptions): void {
+  const missing: string[] = [];
+
+  if (options.registry.events.size > 0 && !options.eventBus) {
+    missing.push("events require an event bus");
+  }
+  if (options.registry.jobs.size > 0 && !options.jobs) {
+    missing.push("jobs require a job dispatcher");
+  }
+
+  if (missing.length > 0) {
+    throw new OutboxRegistryError(
+      `Cannot drain this outbox registry: ${missing.join("; ")}.`,
+    );
+  }
+}
+
 /**
  * Domain event recorder port re-exported for outbox integrations.
  */

package/src/ports/cache.ts

@@ -3,11 +3,35 @@
  */
 export interface CacheSetOptions {
   /**
-   * Time-to-live in seconds. Omit this for a value that does not expire.
+   * Time-to-live in seconds. Values must be positive safe integers. Omit this
+   * for a value that does not expire.
    */
   ttlSeconds?: number;
 }
 
+/**
+ * Resolve and validate the optional TTL shared by cache adapters.
+ *
+ * @param options - Cache write options.
+ * @returns The positive TTL, or `undefined` for a persistent value.
+ */
+export function resolveCacheTtlSeconds(
+  options?: CacheSetOptions,
+): number | undefined {
+  const ttlSeconds = options?.ttlSeconds;
+  if (ttlSeconds === undefined) {
+    return undefined;
+  }
+
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds <= 0) {
+    throw new RangeError(
+      "Cache ttlSeconds must be a positive safe integer when provided.",
+    );
+  }
+
+  return ttlSeconds;
+}
+
 /**
  * App-facing string cache port.
  *
@@ -54,15 +78,12 @@ type MemoryCacheEntry = {
 };
 
 function resolveExpiresAt(options: CacheSetOptions | undefined): number | null {
-  if (options?.ttlSeconds == null) {
+  const ttlSeconds = resolveCacheTtlSeconds(options);
+  if (ttlSeconds === undefined) {
     return null;
   }
 
-  if (options.ttlSeconds <= 0) {
-    return Date.now();
-  }
-
-  return Date.now() + options.ttlSeconds * 1000;
+  return Math.min(Number.MAX_SAFE_INTEGER, Date.now() + ttlSeconds * 1000);
 }
 
 function isExpired(entry: MemoryCacheEntry): boolean {
@@ -120,6 +141,7 @@ export function createMemoryCache(
       return (await getFreshEntry(key)) != null;
     },
     async remember(key, factory, options) {
+      resolveCacheTtlSeconds(options);
       const cached = await cache.get(key);
       if (cached != null) {
         return cached;

package/src/ports/index.ts

@@ -483,7 +483,7 @@ export type { CachePort, CacheSetOptions } from "./cache.js";
 /**
  * Cache helper exports.
  */
-export { createMemoryCache } from "./cache.js";
+export { createMemoryCache, resolveCacheTtlSeconds } from "./cache.js";
 /**
  * Clock port exports.
  */

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 ?? {},