@beignet/core 0.0.51 → 0.0.53

package/src/server/response-finalization.ts

@@ -312,18 +312,18 @@ function getDeclaredCatalogErrorsForStatus(
   );
 }
 
-async function validateCatalogErrorResponse<C extends HttpContractConfig>(
+async function parseCatalogErrorResponse<C extends HttpContractConfig>(
   contract: C,
   res: HttpResponseLike,
-): Promise<void> {
+): Promise<HttpResponseLike> {
   const body = res.body;
-  if (res.status < 400 || !isErrorResponseBody(body)) return;
+  if (res.status < 400 || !isErrorResponseBody(body)) return res;
 
   const declaredErrors = getDeclaredCatalogErrorsForStatus(
     contract,
     res.status,
   );
-  if (declaredErrors.length === 0) return;
+  if (declaredErrors.length === 0) return res;
 
   const matchingError = declaredErrors.find(
     (error) => error.code === body.code,
@@ -346,7 +346,18 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
 
   if (matchingError.details && body.details !== undefined) {
     try {
-      await parseStandardSchema(matchingError.details, body.details);
+      const parsedDetails = await parseStandardSchema(
+        matchingError.details,
+        body.details,
+      );
+      const { details: _details, ...bodyWithoutDetails } = body;
+      return {
+        ...res,
+        body:
+          parsedDetails === undefined
+            ? bodyWithoutDetails
+            : { ...bodyWithoutDetails, details: parsedDetails },
+      };
     } catch (error) {
       if (error instanceof SchemaValidationError) {
         throw new ResponseContractViolationError({
@@ -360,18 +371,20 @@ async function validateCatalogErrorResponse<C extends HttpContractConfig>(
       throw error;
     }
   }
+
+  return res;
 }
 
-async function validateResponseAgainstContract<C extends HttpContractConfig>(
+async function parseResponseAgainstContract<C extends HttpContractConfig>(
   contract: C,
   res: HttpResponseLike,
   responseValidationExemptStatus?: number,
-): Promise<void> {
+): Promise<HttpResponseLike> {
   const statusKey = String(res.status);
   const hasDeclaredStatus = Object.hasOwn(contract.responses, statusKey);
 
   if (!hasDeclaredStatus) {
-    if (Object.keys(contract.responses).length === 0) return;
+    if (Object.keys(contract.responses).length === 0) return res;
 
     throw new ResponseContractViolationError({
       code: "UNDECLARED_RESPONSE_STATUS",
@@ -400,19 +413,22 @@ async function validateResponseAgainstContract<C extends HttpContractConfig>(
         }),
       });
     }
-    return;
+    return res;
   }
 
-  if (!responseSchema) return;
+  if (!responseSchema) return res;
 
   // Binder routes whose use case output schema is the same object as the
   // declared success response schema skip the redundant success-status parse.
   // Error statuses and undeclared statuses are validated unchanged.
-  if (res.status === responseValidationExemptStatus) return;
+  if (res.status === responseValidationExemptStatus) return res;
 
   try {
-    await parseStandardSchema(responseSchema, res.body);
-    await validateCatalogErrorResponse(contract, res);
+    const parsed = {
+      ...res,
+      body: await parseStandardSchema(responseSchema, res.body),
+    };
+    return await parseCatalogErrorResponse(contract, parsed);
   } catch (error) {
     if (error instanceof SchemaValidationError) {
       throw new ResponseContractViolationError({
@@ -463,7 +479,7 @@ export async function finalizeResponse<C extends HttpContractConfig>(
   const normalized = normalizeResponse(res);
   validateHttpResponseSemantics(contract, normalized);
   if (options.validateContract ?? true) {
-    await validateResponseAgainstContract(
+    return parseResponseAgainstContract(
       contract,
       normalized,
       responseValidationExemptStatus,
@@ -490,6 +506,8 @@ export function defaultErrorResponse(
   ctx?: unknown,
 ): HttpResponseLike {
   const requestId = getRequestIdFromContext(ctx);
+  const exposeErrorDetails =
+    process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test";
   return {
     status: 500,
     body: createErrorResponseBody({
@@ -497,7 +515,7 @@ export function defaultErrorResponse(
       message: "Internal server error",
       requestId,
       details:
-        process.env.NODE_ENV !== "production" && err instanceof Error
+        exposeErrorDetails && err instanceof Error
           ? {
               error: {
                 message: err.message,

package/src/server/server.ts

@@ -204,15 +204,18 @@ export type CreateServerOptions<
    * `ports.devtools`) when one is installed.
    *
    * Pass `false` to disable headers and event recording. Context factories
-   * still receive `requestId` and `trace` arguments.
+   * still receive `requestId` and `trace` arguments, and request-scoped
+   * correlation remains available to ambient audit wrappers.
    */
   instrumentation?: ServerInstrumentationOptions<Ctx> | false;
   /**
-   * Whether route-owned responses are validated against the contract's
-   * declared statuses and response schemas before they are sent.
+   * Whether route-owned responses are parsed against the contract's declared
+   * statuses and response schemas before they are sent. The parsed schema
+   * output becomes the response body.
    *
-   * Disable this to trade response guarantees for throughput, mirroring the
-   * client-side `validateResponses` option.
+   * Disable this to send route-owned handler bodies as-is without validation,
+   * unknown-key stripping, or transforms, mirroring the client-side
+   * `validateResponses` option.
    *
    * @default true
    */
@@ -407,9 +410,7 @@ export async function createServer<
     options.instrumentation,
   );
   const hooks = [
-    ...(instrumentation.hook
-      ? [instrumentation.hook as ServerHook<Ctx, FinalPorts>]
-      : []),
+    instrumentation.hook as ServerHook<Ctx, FinalPorts>,
     ...((options.hooks ?? []) as ServerHook<Ctx, FinalPorts>[]),
   ];
   const contracts = options.routes ? contractsFromRoutes(options.routes) : [];

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

@@ -149,20 +149,143 @@ export type UseCaseRouteInputParts<C extends HttpContractConfig> = {
   body: InferBody<C>;
 };
 
+type SegmentPathParam<Segment extends string> = Segment extends `:${infer Name}`
+  ? Name
+  : Segment extends `[${infer Name}]`
+    ? Name
+    : never;
+
+type PathParamNames<Path extends string> = string extends Path
+  ? never
+  : Path extends `${infer Segment}/${infer Rest}`
+    ? SegmentPathParam<Segment> | PathParamNames<Rest>
+    : SegmentPathParam<Path>;
+
+type EmptyBinderInput = Record<never, never>;
+
+declare const UNMERGEABLE_BINDER_INPUT: unique symbol;
+
+type UnmergeableBinderInput = {
+  readonly [UNMERGEABLE_BINDER_INPUT]: true;
+};
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+type BinderObject<T> =
+  IsAny<T> extends true
+    ? UnmergeableBinderInput
+    : [T] extends [object]
+      ? [Extract<T, readonly unknown[]>] extends [never]
+        ? T
+        : UnmergeableBinderInput
+      : UnmergeableBinderInput;
+
+type MergeBinderObjects<LowerPrecedence, HigherPrecedence> = [
+  BinderObject<LowerPrecedence>,
+] extends [UnmergeableBinderInput]
+  ? UnmergeableBinderInput
+  : [BinderObject<HigherPrecedence>] extends [UnmergeableBinderInput]
+    ? UnmergeableBinderInput
+    : Omit<
+        BinderObject<LowerPrecedence>,
+        keyof BinderObject<HigherPrecedence>
+      > &
+        BinderObject<HigherPrecedence>;
+
+type InferredPathInput<C extends HttpContractConfig> = string extends C["path"]
+  ? UnmergeableBinderInput
+  : [PathParamNames<C["path"]>] extends [never]
+    ? EmptyBinderInput
+    : { [K in PathParamNames<C["path"]>]: string };
+
+type BinderPathInput<C extends HttpContractConfig> =
+  C["pathParams"] extends StandardSchemaV1
+    ? InferOutput<C["pathParams"]>
+    : InferredPathInput<C>;
+
+type BinderQueryInput<C extends HttpContractConfig> =
+  C["query"] extends StandardSchemaV1
+    ? InferOutput<C["query"]>
+    : EmptyBinderInput;
+
+type BinderBodyInput<C extends HttpContractConfig> =
+  C["body"] extends StandardSchemaV1
+    ? InferOutput<C["body"]>
+    : EmptyBinderInput;
+
+type HasPathSchema<C extends HttpContractConfig> =
+  C["pathParams"] extends StandardSchemaV1 ? true : false;
+
+type HasQuerySchema<C extends HttpContractConfig> =
+  C["query"] extends StandardSchemaV1 ? true : false;
+
+type HasBodySchema<C extends HttpContractConfig> =
+  C["body"] extends StandardSchemaV1 ? true : false;
+
+type HasInferredPathInput<C extends HttpContractConfig> =
+  string extends C["path"]
+    ? true
+    : [PathParamNames<C["path"]>] extends [never]
+      ? false
+      : true;
+
+type MergedBinderInput<C extends HttpContractConfig> = MergeBinderObjects<
+  MergeBinderObjects<BinderQueryInput<C>, BinderBodyInput<C>>,
+  BinderPathInput<C>
+>;
+
+/**
+ * Input produced when a binder route omits an explicit `input` mapper.
+ *
+ * A sole declared request schema passes through unchanged when the literal
+ * path has no additional inferred parameters. Every other supported default
+ * binding merges object inputs with path over body over query precedence.
+ */
+type DefaultBinderRouteInput<C extends HttpContractConfig> =
+  HasPathSchema<C> extends true
+    ? HasQuerySchema<C> extends true
+      ? MergedBinderInput<C>
+      : HasBodySchema<C> extends true
+        ? MergedBinderInput<C>
+        : BinderPathInput<C>
+    : HasQuerySchema<C> extends true
+      ? HasBodySchema<C> extends true
+        ? MergedBinderInput<C>
+        : HasInferredPathInput<C> extends true
+          ? MergedBinderInput<C>
+          : BinderQueryInput<C>
+      : HasBodySchema<C> extends true
+        ? HasInferredPathInput<C> extends true
+          ? MergedBinderInput<C>
+          : BinderBodyInput<C>
+        : BinderPathInput<C>;
+
+type UseCaseRouteInputMode = "default" | "mapped";
+
 /**
  * Constraint that checks a use case against the route that binds it.
  *
  * Produces a readable branded mismatch object on the `useCase` property when
- * the use case requires a context the server does not provide, or when its
- * output does not match the contract's declared success response schema.
+ * the use case requires a context the server does not provide, when its
+ * output does not match the contract's declared success response schema, or
+ * when the default binder input does not satisfy the use case input.
  */
-export type UseCaseFitsRoute<Ctx, C extends HttpContractConfig, UC> = [
+export type UseCaseFitsRoute<
   Ctx,
-] extends [UseCaseRouteCtx<UC>]
+  C extends HttpContractConfig,
+  UC,
+  InputMode extends UseCaseRouteInputMode = "default",
+> = [Ctx] extends [UseCaseRouteCtx<UC>]
   ? [UseCaseRouteOutput<UC>] extends [
       SuccessBodyFromKeys<C["responses"], Success2xxKeys<C["responses"]>>,
     ]
-    ? unknown
+    ? InputMode extends "mapped"
+      ? unknown
+      : [DefaultBinderRouteInput<C>] extends [UseCaseRouteInput<UC>]
+        ? unknown
+        : {
+            "~beignetError": "default binder input does not match the use case input; add an input mapper";
+          }
     : {
         "~beignetError": "useCase output does not match the contract's success response schema";
       }
@@ -185,21 +308,34 @@ type UseCaseRouteShape<
    * Route-scoped hooks that run after group hooks and before the use case.
    */
   hooks?: Hooks;
-  /**
-   * Use case bound directly to the contract.
-   */
-  useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC>;
-  /**
-   * Map parsed request parts to the use case input.
-   *
-   * 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;
-} & BinderStatusOption<C>;
+} & (
+  | {
+      /**
+       * Use case bound directly to the contract. The default binder input
+       * must satisfy the use case input type.
+       */
+      useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC>;
+      input?: never;
+    }
+  | {
+      /**
+       * Use case bound directly to the contract through an explicit input
+       * mapper.
+       */
+      useCase: UC & UseCaseFitsRoute<HandlerCtx, C, UC, "mapped">;
+      /**
+       * Map parsed request parts to the use case input.
+       *
+       * 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>;
+    }
+) &
+  BinderStatusOption<C>;
 
 /**
  * Route registration that binds a contract directly to a use case.
@@ -271,11 +407,25 @@ export type ValidatedRouteInput<Ctx, E> = E extends {
     ? {
         contract: CL;
         hooks?: HooksOf<E>;
-        useCase: UC &
-          UseCaseFitsRoute<Ctx & AddedCtxFromHooks<HooksOf<E>>, C, UC>;
-        input?: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
         handle?: never;
-      } & BinderStatusOption<C>
+      } & (
+        | {
+            useCase: UC &
+              UseCaseFitsRoute<Ctx & AddedCtxFromHooks<HooksOf<E>>, C, UC>;
+            input?: never;
+          }
+        | {
+            useCase: UC &
+              UseCaseFitsRoute<
+                Ctx & AddedCtxFromHooks<HooksOf<E>>,
+                C,
+                UC,
+                "mapped"
+              >;
+            input: (parts: UseCaseRouteInputParts<C>) => UseCaseRouteInput<UC>;
+          }
+      ) &
+        BinderStatusOption<C>
     : unknown
   : unknown;
 
@@ -322,6 +472,49 @@ export type RuntimeUseCaseRouteDef = {
   status?: number;
 };
 
+type UseCaseInputValidationFailure = Error & {
+  name: "UseCaseValidationError";
+  phase: "input";
+  useCaseName: string;
+};
+
+function isUseCaseInputValidationFailure(
+  error: unknown,
+  useCaseName: string,
+): error is UseCaseInputValidationFailure {
+  if (!(error instanceof Error)) return false;
+  const candidate = error as Partial<UseCaseInputValidationFailure>;
+  return (
+    candidate.name === "UseCaseValidationError" &&
+    candidate.phase === "input" &&
+    candidate.useCaseName === useCaseName
+  );
+}
+
+/**
+ * Internal framework error raised when a type-erased binder route produces an
+ * input that the bound use case rejects.
+ */
+export class UseCaseRouteInputValidationError extends Error {
+  readonly code = "USE_CASE_INPUT_VALIDATION_ERROR";
+  readonly contractName: string;
+  readonly useCaseName: string;
+
+  constructor(args: {
+    contractName: string;
+    useCaseName: string;
+    cause: UseCaseInputValidationFailure;
+  }) {
+    super(
+      `Default binder input for contract "${args.contractName}" does not satisfy use case "${args.useCaseName}". Add an explicit input mapper.`,
+      { cause: args.cause },
+    );
+    this.name = "UseCaseRouteInputValidationError";
+    this.contractName = args.contractName;
+    this.useCaseName = args.useCaseName;
+  }
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -458,10 +651,24 @@ export function createUseCaseRouteHandler<Ctx, C extends HttpContractConfig>(
         : defaultBinderInput(parts);
     const run = passSingle && trustedRun ? trustedRun : def.useCase.run;
 
-    return {
-      status,
-      body: await run.call(def.useCase, { ctx, input }),
-    };
+    try {
+      return {
+        status,
+        body: await run.call(def.useCase, { ctx, input }),
+      };
+    } catch (error) {
+      if (
+        !def.input &&
+        isUseCaseInputValidationFailure(error, def.useCase.name)
+      ) {
+        throw new UseCaseRouteInputValidationError({
+          contractName: contract.name,
+          useCaseName: def.useCase.name,
+          cause: error,
+        });
+      }
+      throw error;
+    }
   };
 
   return {

package/src/uploads/index.ts

@@ -968,29 +968,47 @@ export function createUploadRouter<Ctx>(
             },
           });
         }
-        const object = needsUploadBodyVerification(upload, file)
+        const verifyBody = needsUploadBodyVerification(upload, file);
+        const objectBody = verifyBody
           ? await options.storage.get(file.key)
+          : null;
+        const object = verifyBody
+          ? objectBody
           : await options.storage.stat(file.key);
         if (!object) {
           throw new UploadObjectNotFoundError({
             message: `Uploaded object "${file.key}" was not found.`,
           });
         }
-        assertStoredObject(upload, file, object);
-        const verified = await verifyStoredUploadFile(upload, file, object);
-        const completedObject = storageObjectMetadata(object);
-        const completedFile = {
-          ...file,
-          ...(verified.checksum ? { checksum: verified.checksum } : {}),
-          object: completedObject,
-        };
-        await assertVerifiedFile(upload, {
-          ctx,
-          metadata,
-          file: completedFile,
-          storage: options.storage,
-        });
-        files.push(completedFile);
+        let operationFailed = false;
+        try {
+          assertStoredObject(upload, file, object);
+          const verified = await verifyStoredUploadFile(upload, file, object);
+          const completedObject = storageObjectMetadata(object);
+          const completedFile = {
+            ...file,
+            ...(verified.checksum ? { checksum: verified.checksum } : {}),
+            object: completedObject,
+          };
+          await assertVerifiedFile(upload, {
+            ctx,
+            metadata,
+            file: completedFile,
+            storage: options.storage,
+          });
+          files.push(completedFile);
+        } catch (error) {
+          operationFailed = true;
+          throw error;
+        } finally {
+          if (objectBody && !objectBody.bodyUsed) {
+            if (operationFailed) {
+              await objectBody.cancel().catch(() => undefined);
+            } else {
+              await objectBody.cancel();
+            }
+          }
+        }
       }
 
       const result = await upload.onComplete?.({ ctx, metadata, files });