Update to Body consistency in http request

docs/libraries/http/reference/decorators.md

@@ -10,7 +10,10 @@ toc_max_heading_level: 3
 
 ### `@body` {#@TypeSpec.Http.body}
 
-Explicitly specify that this property is to be set as the body
+Explicitly specify that this property type will be exactly the HTTP body.
+
+This means that any properties under `@body` cannot be marked as headers, query parameters, or path parameters.
+If wanting to change the resolution of the body but still mix parameters, use `@bodyRoot`.
 
 ```typespec
 @TypeSpec.Http.body
@@ -33,6 +36,69 @@ op download(): {
 };
 ```
 
+### `@bodyIgnore` {#@TypeSpec.Http.bodyIgnore}
+
+Specify that this property shouldn't be included in the HTTP body.
+This can be useful when bundling metadata together that would result in an empty property to be included in the body.
+
+```typespec
+@TypeSpec.Http.bodyIgnore
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+
+None
+
+#### Examples
+
+```typespec
+op upload(
+  name: string,
+  @bodyIgnore headers: {
+    @header id: string;
+  },
+): void;
+```
+
+### `@bodyRoot` {#@TypeSpec.Http.bodyRoot}
+
+Specify that the body resolution should be resolved from that property.
+By default the body is resolved by including all properties in the operation request/response that are not metadata.
+This allows to nest the body in a property while still allowing to use headers, query parameters, and path parameters in the same model.
+
+```typespec
+@TypeSpec.Http.bodyRoot
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+
+None
+
+#### Examples
+
+```typespec
+op upload(
+  @bodyRoot user: {
+    name: string;
+    @header id: string;
+  },
+): void;
+op download(): {
+  @bodyRoot user: {
+    name: string;
+    @header id: string;
+  };
+};
+```
+
 ### `@delete` {#@TypeSpec.Http.delete}
 
 Specify the HTTP verb for the target operation to be `DELETE`.

docs/libraries/http/reference/index.mdx

@@ -36,6 +36,8 @@ npm install --save-peer @typespec/http
 ### Decorators
 
 - [`@body`](./decorators.md#@TypeSpec.Http.body)
+- [`@bodyIgnore`](./decorators.md#@TypeSpec.Http.bodyIgnore)
+- [`@bodyRoot`](./decorators.md#@TypeSpec.Http.bodyRoot)
 - [`@delete`](./decorators.md#@TypeSpec.Http.delete)
 - [`@get`](./decorators.md#@TypeSpec.Http.get)
 - [`@head`](./decorators.md#@TypeSpec.Http.head)

packages/http/README.md

@@ -37,6 +37,8 @@ Available ruleSets:
 ### TypeSpec.Http
 
 - [`@body`](#@body)
+- [`@bodyIgnore`](#@bodyignore)
+- [`@bodyRoot`](#@bodyroot)
 - [`@delete`](#@delete)
 - [`@get`](#@get)
 - [`@head`](#@head)
@@ -55,7 +57,10 @@ Available ruleSets:
 
 #### `@body`
 
-Explicitly specify that this property is to be set as the body
+Explicitly specify that this property type will be exactly the HTTP body.
+
+This means that any properties under `@body` cannot be marked as headers, query parameters, or path parameters.
+If wanting to change the resolution of the body but still mix parameters, use `@bodyRoot`.
 
 ```typespec
 @TypeSpec.Http.body
@@ -78,6 +83,69 @@ op download(): {
 };
 ```
 
+#### `@bodyIgnore`
+
+Specify that this property shouldn't be included in the HTTP body.
+This can be useful when bundling metadata together that would result in an empty property to be included in the body.
+
+```typespec
+@TypeSpec.Http.bodyIgnore
+```
+
+##### Target
+
+`ModelProperty`
+
+##### Parameters
+
+None
+
+##### Examples
+
+```typespec
+op upload(
+  name: string,
+  @bodyIgnore headers: {
+    @header id: string;
+  },
+): void;
+```
+
+#### `@bodyRoot`
+
+Specify that the body resolution should be resolved from that property.
+By default the body is resolved by including all properties in the operation request/response that are not metadata.
+This allows to nest the body in a property while still allowing to use headers, query parameters, and path parameters in the same model.
+
+```typespec
+@TypeSpec.Http.bodyRoot
+```
+
+##### Target
+
+`ModelProperty`
+
+##### Parameters
+
+None
+
+##### Examples
+
+```typespec
+op upload(
+  @bodyRoot user: {
+    name: string;
+    @header id: string;
+  },
+): void;
+op download(): {
+  @bodyRoot user: {
+    name: string;
+    @header id: string;
+  };
+};
+```
+
 #### `@delete`
 
 Specify the HTTP verb for the target operation to be `DELETE`.

packages/http/lib/http-decorators.tsp

@@ -83,7 +83,10 @@ extern dec query(target: ModelProperty, queryNameOrOptions?: string | QueryOptio
 extern dec path(target: ModelProperty, paramName?: valueof string);
 
 /**
- * Explicitly specify that this property is to be set as the body
+ * Explicitly specify that this property type will be exactly the HTTP body.
+ *
+ * This means that any properties under `@body` cannot be marked as headers, query parameters, or path parameters.
+ * If wanting to change the resolution of the body but still mix parameters, use `@bodyRoot`.
  *
  * @example
  *
@@ -94,6 +97,31 @@ extern dec path(target: ModelProperty, paramName?: valueof string);
  */
 extern dec body(target: ModelProperty);
 
+/**
+ * Specify that the body resolution should be resolved from that property.
+ * By default the body is resolved by including all properties in the operation request/response that are not metadata.
+ * This allows to nest the body in a property while still allowing to use headers, query parameters, and path parameters in the same model.
+ *
+ * @example
+ *
+ * ```typespec
+ * op upload(@bodyRoot user: {name: string, @header id: string}): void;
+ * op download(): {@bodyRoot user: {name: string, @header id: string}};
+ * ```
+ */
+extern dec bodyRoot(target: ModelProperty);
+/**
+ * Specify that this property shouldn't be included in the HTTP body.
+ * This can be useful when bundling metadata together that would result in an empty property to be included in the body.
+ *
+ * @example
+ *
+ * ```typespec
+ * op upload(name: string, @bodyIgnore headers: {@header id: string}): void;
+ * ```
+ */
+extern dec bodyIgnore(target: ModelProperty);
+
 /**
  * Specify the status code for this response. Property type must be a status code integer or a union of status code integer.
  *

packages/http/src/body.ts

@@ -0,0 +1,144 @@
+import {
+  Diagnostic,
+  DuplicateTracker,
+  ModelProperty,
+  Program,
+  Type,
+  createDiagnosticCollector,
+  filterModelProperties,
+  getDiscriminator,
+  isArrayModelType,
+  navigateType,
+} from "@typespec/compiler";
+import {
+  isBody,
+  isBodyRoot,
+  isHeader,
+  isPathParam,
+  isQueryParam,
+  isStatusCode,
+} from "./decorators.js";
+import { createDiagnostic } from "./lib.js";
+import { Visibility, isVisible } from "./metadata.js";
+
+export interface ResolvedBody {
+  readonly type: Type;
+  /** `true` if the body was specified with `@body` */
+  readonly isExplicit: boolean;
+  /** If body is defined with `@body` or `@bodyRoot` this is the property */
+  readonly property?: ModelProperty;
+}
+
+export function resolveBody(
+  program: Program,
+  requestOrResponseType: Type,
+  metadata: Set<ModelProperty>,
+  rootPropertyMap: Map<ModelProperty, ModelProperty>,
+  visibility: Visibility
+): [ResolvedBody | undefined, readonly Diagnostic[]] {
+  const diagnostics = createDiagnosticCollector();
+  // non-model or intrinsic/array model -> response body is response type
+  if (requestOrResponseType.kind !== "Model" || isArrayModelType(program, requestOrResponseType)) {
+    return diagnostics.wrap({ type: requestOrResponseType, isExplicit: false });
+  }
+
+  const duplicateTracker = new DuplicateTracker<string, Type>();
+
+  // look for explicit body
+  let resolvedBody: ResolvedBody | undefined;
+  for (const property of metadata) {
+    const isBodyVal = isBody(program, property);
+    const isBodyRootVal = isBodyRoot(program, property);
+    if (isBodyVal || isBodyRootVal) {
+      duplicateTracker.track("body", property);
+      if (resolvedBody === undefined) {
+        resolvedBody = { type: property.type, isExplicit: isBodyVal, property };
+      }
+    }
+  }
+  for (const [_, items] of duplicateTracker.entries()) {
+    for (const prop of items) {
+      diagnostics.add(
+        createDiagnostic({
+          code: "duplicate-body",
+          target: prop,
+        })
+      );
+    }
+  }
+  if (resolvedBody === undefined) {
+    // Special case if the model as a parent model then we'll return an empty object as this is assumed to be a nominal type.
+    // Special Case if the model has an indexer then it means it can return props so cannot be void.
+    if (requestOrResponseType.baseModel || requestOrResponseType.indexer) {
+      return diagnostics.wrap({ type: requestOrResponseType, isExplicit: false });
+    }
+    // Special case for legacy purposes if the return type is an empty model with only @discriminator("xyz")
+    // Then we still want to return that object as it technically always has a body with that implicit property.
+    if (
+      requestOrResponseType.derivedModels.length > 0 &&
+      getDiscriminator(program, requestOrResponseType)
+    ) {
+      return diagnostics.wrap({ type: requestOrResponseType, isExplicit: false });
+    }
+  }
+
+  const bodyRoot = resolvedBody?.property ? rootPropertyMap.get(resolvedBody.property) : undefined;
+
+  const unannotatedProperties = filterModelProperties(
+    program,
+    requestOrResponseType,
+    (p) => !metadata.has(p) && p !== bodyRoot && isVisible(program, p, visibility)
+  );
+
+  if (unannotatedProperties.properties.size > 0) {
+    if (resolvedBody === undefined) {
+      return diagnostics.wrap({ type: unannotatedProperties, isExplicit: false });
+    } else {
+      diagnostics.add(
+        createDiagnostic({
+          code: "duplicate-body",
+          messageId: "bodyAndUnannotated",
+          target: requestOrResponseType,
+        })
+      );
+    }
+  }
+
+  return diagnostics.wrap(resolvedBody);
+}
+
+/** Validate a property marked with `@body` */
+export function validateBodyProperty(
+  program: Program,
+  property: ModelProperty
+): [boolean, readonly Diagnostic[]] {
+  const diagnostics = createDiagnosticCollector();
+  navigateType(
+    property.type,
+    {
+      modelProperty: (prop) => {
+        const kind = isHeader(program, prop)
+          ? "header"
+          : isQueryParam(program, prop)
+            ? "query"
+            : isPathParam(program, prop)
+              ? "path"
+              : isStatusCode(program, prop)
+                ? "statusCode"
+                : undefined;
+
+        if (kind) {
+          diagnostics.add(
+            createDiagnostic({
+              code: "metadata-ignored",
+              format: { kind },
+              target: prop,
+            })
+          );
+        }
+      },
+    },
+    {}
+  );
+  return diagnostics.wrap(diagnostics.diagnostics.length === 0);
+}