Removing body depiction from negative response to HEAD requests (#2859)

Fixes #2858 

Noticed by @coderabbitai in
#2857 (comment)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated API documentation for several HEAD endpoints to remove
detailed error response content, reflecting that no payload is returned
for negative responses.

* **Refactor**
* Simplified logic for determining response content in HEAD requests,
now relying solely on the HTTP method.
* Streamlined type definitions for negative responses of HEAD endpoints
to indicate no content is returned.

* **Tests**
* Updated tests to align with the simplified response content logic for
HEAD requests.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: RobinTail

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Version 24
 
+### v24.7.3
+
+- Fixed the depiction of the negative response to `HEAD` requests:
+  - Should have no response body, exactly as the positive one;
+  - This version corrects the implementation introduced in [v24.7.0](#v2470).
+
 ### v24.7.2
 
 - Fixed the negative response MIME type for ~~`arrayResultHandler`~~ (deprecated entity):
@@ -24,10 +30,10 @@
   - It is the built-in feature of Express to handle `HEAD` requests by the handlers for `GET` requests;
   - Therefore, each `Endpoint` supporting `get` method also handles `head` requests (no work needed);
   - Added `HEAD` method to CORS response headers, along with `OPTIONS`, for `GET` method supporting endpoints;
-  - Positive response to `HEAD` request should contain same headers as `GET` would, but without the body:
+  - ~~Positive~~ Response to `HEAD` request should contain same headers as `GET` would, but without the body:
     - Added `head` request depiction to the generated `Documentation`;
     - Added `head` request types to the generated `Integration` client;
-  - Positive response to `HEAD` request should contain the `Content-Length` header:
+  - ~~Positive~~ Response to `HEAD` request should contain the `Content-Length` header:
     - `ResultHandler`s using `response.send()` (as well as its shorthands such as `.json()`) automatically do that
       instead of sending the response body (no work needed);
     - Other approaches, such as stream piping, might require to implement `Content-Length` header for `HEAD` requests;

example/example.client.ts

@@ -54,12 +54,7 @@ interface HeadV1UserRetrievePositiveResponseVariants {
 }
 
 /** head /v1/user/retrieve */
-type HeadV1UserRetrieveNegativeVariant1 = {
-  status: "error";
-  error: {
-    message: string;
-  };
-};
+type HeadV1UserRetrieveNegativeVariant1 = undefined;
 
 /** head /v1/user/retrieve */
 interface HeadV1UserRetrieveNegativeResponseVariants {
@@ -198,7 +193,7 @@ interface HeadV1UserListPositiveResponseVariants {
 }
 
 /** head /v1/user/list */
-type HeadV1UserListNegativeVariant1 = string;
+type HeadV1UserListNegativeVariant1 = undefined;
 
 /** head /v1/user/list */
 interface HeadV1UserListNegativeResponseVariants {
@@ -240,7 +235,7 @@ interface HeadV1AvatarSendPositiveResponseVariants {
 }
 
 /** head /v1/avatar/send */
-type HeadV1AvatarSendNegativeVariant1 = string;
+type HeadV1AvatarSendNegativeVariant1 = undefined;
 
 /** head /v1/avatar/send */
 interface HeadV1AvatarSendNegativeResponseVariants {
@@ -282,7 +277,7 @@ interface HeadV1AvatarStreamPositiveResponseVariants {
 }
 
 /** head /v1/avatar/stream */
-type HeadV1AvatarStreamNegativeVariant1 = string;
+type HeadV1AvatarStreamNegativeVariant1 = undefined;
 
 /** head /v1/avatar/stream */
 interface HeadV1AvatarStreamNegativeResponseVariants {
@@ -395,7 +390,7 @@ interface HeadV1EventsStreamPositiveResponseVariants {
 }
 
 /** head /v1/events/stream */
-type HeadV1EventsStreamNegativeVariant1 = string;
+type HeadV1EventsStreamNegativeVariant1 = undefined;
 
 /** head /v1/events/stream */
 interface HeadV1EventsStreamNegativeResponseVariants {

example/example.documentation.yaml

@@ -100,32 +100,6 @@ paths:
           description: HEAD /v1/user/retrieve Positive response
         "400":
           description: HEAD /v1/user/retrieve Negative response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  status:
-                    type: string
-                    const: error
-                  error:
-                    type: object
-                    properties:
-                      message:
-                        type: string
-                    required:
-                      - message
-                    additionalProperties: false
-                required:
-                  - status
-                  - error
-                additionalProperties: false
-              examples:
-                example1:
-                  value:
-                    status: error
-                    error:
-                      message: Sample error message
   /v1/user/{id}/remove:
     delete:
       operationId: DeleteV1UserIdRemove
@@ -456,13 +430,6 @@ paths:
           description: HEAD /v1/user/list Positive response
         "400":
           description: HEAD /v1/user/list Negative response
-          content:
-            text/plain:
-              schema:
-                type: string
-              examples:
-                example1:
-                  value: Sample error message
   /v1/avatar/send:
     get:
       operationId: GetV1AvatarSend
@@ -512,10 +479,6 @@ paths:
           description: HEAD /v1/avatar/send Positive response
         "400":
           description: HEAD /v1/avatar/send Negative response
-          content:
-            text/plain:
-              schema:
-                type: string
   /v1/avatar/stream:
     get:
       operationId: GetV1AvatarStream
@@ -565,10 +528,6 @@ paths:
           description: HEAD /v1/avatar/stream Positive response
         "400":
           description: HEAD /v1/avatar/stream Negative response
-          content:
-            text/plain:
-              schema:
-                type: string
   /v1/avatar/upload:
     post:
       operationId: PostV1AvatarUpload
@@ -790,10 +749,6 @@ paths:
           description: HEAD /v1/events/stream Positive response
         "400":
           description: HEAD /v1/events/stream Negative response
-          content:
-            text/plain:
-              schema:
-                type: string
   /v1/forms/feedback:
     post:
       operationId: PostV1FormsFeedback

express-zod-api/src/common-helpers.ts

@@ -11,7 +11,7 @@ import {
   Method,
   CORSMethod,
 } from "./method";
-import { ResponseVariant } from "./api-response";
+import { NormalizedResponse } from "./api-response";
 
 /** @desc this type does not allow props assignment, but it works for reading them when merged with another interface */
 export type EmptyObject = z.output<EmptySchema>;
@@ -143,7 +143,8 @@ export const isProduction = R.memoizeWith(
   () => process.env.NODE_ENV === "production", // eslint-disable-line no-restricted-syntax -- memoized
 );
 
-export const doesImplyContent = (
+export const shouldHaveContent = (
   method: ClientMethod,
-  responseVariant: ResponseVariant,
-) => !(method === "head" && responseVariant === "positive");
+  mimeTypes: NormalizedResponse["mimeTypes"],
+): mimeTypes is NonNullable<NormalizedResponse["mimeTypes"]> =>
+  Boolean(mimeTypes) && method !== "head";

express-zod-api/src/documentation-helpers.ts

@@ -25,10 +25,10 @@ import {
 } from "openapi3-ts/oas31";
 import * as R from "ramda";
 import { z } from "zod/v4";
-import { ResponseVariant } from "./api-response";
+import { NormalizedResponse, ResponseVariant } from "./api-response";
 import { ezBufferBrand } from "./buffer-schema";
 import {
-  doesImplyContent,
+  shouldHaveContent,
   FlatObject,
   getRoutePathParams,
   getTransformedType,
@@ -494,12 +494,12 @@ export const depictResponse = ({
   composition: "inline" | "components";
   description?: string;
   brandHandling?: BrandHandling;
-  mimeTypes: ReadonlyArray<string> | null;
+  mimeTypes: NormalizedResponse["mimeTypes"];
   variant: ResponseVariant;
   statusCode: number;
   hasMultipleStatusCodes: boolean;
 }): ResponseObject => {
-  if (!mimeTypes || !doesImplyContent(method, variant)) return { description };
+  if (!shouldHaveContent(method, mimeTypes)) return { description };
   const response = asOAS(
     depict(schema, {
       rules: { ...brandHandling, ...depicters },

express-zod-api/src/integration.ts

@@ -14,7 +14,7 @@ import {
   makeLiteralType,
   makeUnion,
 } from "./typescript-api";
-import { doesImplyContent, makeCleanId } from "./common-helpers";
+import { shouldHaveContent, makeCleanId } from "./common-helpers";
 import { loadPeer } from "./peer-helpers";
 import { Routing } from "./routing";
 import { OnEndpoint, walkRouting, withHead } from "./routing-walker";
@@ -107,8 +107,7 @@ export class Integration extends IntegrationBase {
         (agg, responseVariant) => {
           const responses = endpoint.getResponses(responseVariant);
           const props = R.chain(([idx, { schema, mimeTypes, statusCodes }]) => {
-            const hasContent =
-              mimeTypes && doesImplyContent(method, responseVariant);
+            const hasContent = shouldHaveContent(method, mimeTypes);
             const variantType = makeType(
               entitle(responseVariant, "variant", `${idx + 1}`),
               zodToTs(hasContent ? schema : noContent, ctxOut),