Multipart explicit parts

.chronus/changes/feature-multipart-v2-2024-4-14-16-27-48.md

@@ -0,0 +1,6 @@
+---
+changeKind: internal
+packages:
+  - "@typespec/rest"
+---
+

.chronus/changes/feature-multipart-v2-2024-4-14-22-58-52.md

@@ -0,0 +1,15 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+Add new multipart handling. Using `@multipartBody` with `HttpPart<Type, Options>`. See [multipart docs] for more information https://typespec.io/docs/next/libraries/http/multipart
+
+  ```tsp
+  op upload(@header contentType: "multipart/mixed", @multipartBody body: {
+    name: HttpPart<string>;
+    avatar: HttpPart<bytes>[];
+  }): void;
+  ```

.chronus/changes/feature-multipart-v2-2024-4-14-23-5-59.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: fix
+packages:
+  - "@typespec/openapi3"
+---
+
+Add support for new multipart constructs in http library

.vscode/settings.json

@@ -10,6 +10,7 @@
     "**/node_modules/**": true,
     "packages/compiler/templates/__snapshots__/**": true,
     "packages/website/versioned_docs/**": true,
+    "packages/http-client-csharp/**/Generated/**": true,
     "packages/samples/scratch/**": false // Those files are in gitignore but we still want to search for them
   },
   "files.exclude": {

docs/libraries/http/reference/data-types.md

@@ -205,6 +205,20 @@ model TypeSpec.Http.CreatedResponse
 | ---------- | ----- | ---------------- |
 | statusCode | `201` | The status code. |
 
+### `File` {#TypeSpec.Http.File}
+
+```typespec
+model TypeSpec.Http.File
+```
+
+#### Properties
+
+| Name         | Type     | Description |
+| ------------ | -------- | ----------- |
+| contentType? | `string` |             |
+| filename?    | `string` |             |
+| contents     | `bytes`  |             |
+
 ### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse}
 
 Access is forbidden.
@@ -234,6 +248,35 @@ model TypeSpec.Http.HeaderOptions
 | name?   | `string`                                                              | Name of the header when sent over HTTP.                   |
 | format? | `"csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used. |
 
+### `HttpPart` {#TypeSpec.Http.HttpPart}
+
+```typespec
+model TypeSpec.Http.HttpPart<Type, Options>
+```
+
+#### Template Parameters
+
+| Name    | Description |
+| ------- | ----------- |
+| Type    |             |
+| Options |             |
+
+#### Properties
+
+None
+
+### `HttpPartOptions` {#TypeSpec.Http.HttpPartOptions}
+
+```typespec
+model TypeSpec.Http.HttpPartOptions
+```
+
+#### Properties
+
+| Name  | Type     | Description                                 |
+| ----- | -------- | ------------------------------------------- |
+| name? | `string` | Name of the part when using the array form. |
+
 ### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow}
 
 Implicit flow

docs/libraries/http/reference/decorators.md

@@ -225,6 +225,32 @@ Specify if inapplicable metadata should be included in the payload for the given
 | ----- | ----------------- | --------------------------------------------------------------- |
 | value | `valueof boolean` | If true, inapplicable metadata will be included in the payload. |
 
+### `@multipartBody` {#@TypeSpec.Http.multipartBody}
+
+```typespec
+@TypeSpec.Http.multipartBody
+```
+
+#### Target
+
+`ModelProperty`
+
+#### Parameters
+
+None
+
+#### Examples
+
+```tsp
+op upload(
+  @header `content-type`: "multipart/form-data",
+  @multipartBody body: {
+    fullName: HttpPart<string>;
+    headShots: HttpPart<Image>[];
+  },
+): void;
+```
+
 ### `@patch` {#@TypeSpec.Http.patch}
 
 Specify the HTTP verb for the target operation to be `PATCH`.

docs/libraries/http/reference/index.mdx

@@ -43,6 +43,7 @@ npm install --save-peer @typespec/http
 - [`@head`](./decorators.md#@TypeSpec.Http.head)
 - [`@header`](./decorators.md#@TypeSpec.Http.header)
 - [`@includeInapplicableMetadataInPayload`](./decorators.md#@TypeSpec.Http.includeInapplicableMetadataInPayload)
+- [`@multipartBody`](./decorators.md#@TypeSpec.Http.multipartBody)
 - [`@patch`](./decorators.md#@TypeSpec.Http.patch)
 - [`@path`](./decorators.md#@TypeSpec.Http.path)
 - [`@post`](./decorators.md#@TypeSpec.Http.post)
@@ -66,8 +67,11 @@ npm install --save-peer @typespec/http
 - [`ClientCredentialsFlow`](./data-types.md#TypeSpec.Http.ClientCredentialsFlow)
 - [`ConflictResponse`](./data-types.md#TypeSpec.Http.ConflictResponse)
 - [`CreatedResponse`](./data-types.md#TypeSpec.Http.CreatedResponse)
+- [`File`](./data-types.md#TypeSpec.Http.File)
 - [`ForbiddenResponse`](./data-types.md#TypeSpec.Http.ForbiddenResponse)
 - [`HeaderOptions`](./data-types.md#TypeSpec.Http.HeaderOptions)
+- [`HttpPart`](./data-types.md#TypeSpec.Http.HttpPart)
+- [`HttpPartOptions`](./data-types.md#TypeSpec.Http.HttpPartOptions)
 - [`ImplicitFlow`](./data-types.md#TypeSpec.Http.ImplicitFlow)
 - [`LocationHeader`](./data-types.md#TypeSpec.Http.LocationHeader)
 - [`MovedResponse`](./data-types.md#TypeSpec.Http.MovedResponse)

packages/http/README.md

@@ -44,6 +44,7 @@ Available ruleSets:
 - [`@head`](#@head)
 - [`@header`](#@header)
 - [`@includeInapplicableMetadataInPayload`](#@includeinapplicablemetadatainpayload)
+- [`@multipartBody`](#@multipartbody)
 - [`@patch`](#@patch)
 - [`@path`](#@path)
 - [`@post`](#@post)
@@ -272,6 +273,32 @@ Specify if inapplicable metadata should be included in the payload for the given
 | ----- | ----------------- | --------------------------------------------------------------- |
 | value | `valueof boolean` | If true, inapplicable metadata will be included in the payload. |
 
+#### `@multipartBody`
+
+```typespec
+@TypeSpec.Http.multipartBody
+```
+
+##### Target
+
+`ModelProperty`
+
+##### Parameters
+
+None
+
+##### Examples
+
+```tsp
+op upload(
+  @header `content-type`: "multipart/form-data",
+  @multipartBody body: {
+    fullName: HttpPart<string>;
+    headShots: HttpPart<Image>[];
+  },
+): void;
+```
+
 #### `@patch`
 
 Specify the HTTP verb for the target operation to be `PATCH`.

packages/http/generated-defs/TypeSpec.Http.Private.ts

@@ -1,3 +1,12 @@
-import type { DecoratorContext, Model } from "@typespec/compiler";
+import type { DecoratorContext, Model, Type } from "@typespec/compiler";
 
 export type PlainDataDecorator = (context: DecoratorContext, target: Model) => void;
+
+export type HttpFileDecorator = (context: DecoratorContext, target: Model) => void;
+
+export type HttpPartDecorator = (
+  context: DecoratorContext,
+  target: Model,
+  type: Type,
+  options: unknown
+) => void;

packages/http/generated-defs/TypeSpec.Http.ts

@@ -111,6 +111,23 @@ export type BodyRootDecorator = (context: DecoratorContext, target: ModelPropert
  */
 export type BodyIgnoreDecorator = (context: DecoratorContext, target: ModelProperty) => void;
 
+/**
+ *
+ *
+ *
+ * @example
+ * ```tsp
+ * op upload(
+ *   @header `content-type`: "multipart/form-data",
+ *   @multipartBody body: {
+ *     fullName: HttpPart<string>,
+ *     headShots: HttpPart<Image>[]
+ *   }
+ * ): void;
+ * ```
+ */
+export type MultipartBodyDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+
 /**
  * Specify the HTTP verb for the target operation to be `GET`.
  *

packages/http/generated-defs/TypeSpec.Http.ts-test.ts

@@ -8,6 +8,7 @@ import {
   $head,
   $header,
   $includeInapplicableMetadataInPayload,
+  $multipartBody,
   $patch,
   $path,
   $post,
@@ -28,6 +29,7 @@ import type {
   HeadDecorator,
   HeaderDecorator,
   IncludeInapplicableMetadataInPayloadDecorator,
+  MultipartBodyDecorator,
   PatchDecorator,
   PathDecorator,
   PostDecorator,
@@ -48,6 +50,7 @@ type Decorators = {
   $path: PathDecorator;
   $bodyRoot: BodyRootDecorator;
   $bodyIgnore: BodyIgnoreDecorator;
+  $multipartBody: MultipartBodyDecorator;
   $get: GetDecorator;
   $put: PutDecorator;
   $post: PostDecorator;
@@ -70,6 +73,7 @@ const _: Decorators = {
   $path,
   $bodyRoot,
   $bodyIgnore,
+  $multipartBody,
   $get,
   $put,
   $post,

packages/http/lib/http-decorators.tsp → packages/http/lib/decorators.tsp

@@ -122,6 +122,21 @@ extern dec bodyRoot(target: ModelProperty);
  */
 extern dec bodyIgnore(target: ModelProperty);
 
+/**
+ * @example
+ *
+ * ```tsp
+ * op upload(
+ *   @header `content-type`: "multipart/form-data",
+ *   @multipartBody body: {
+ *     fullName: HttpPart<string>,
+ *     headShots: HttpPart<Image>[]
+ *   }
+ * ): void;
+ * ```
+ */
+extern dec multipartBody(target: ModelProperty);
+
 /**
  * Specify the status code for this response. Property type must be a status code integer or a union of status code integer.
  *
@@ -291,10 +306,3 @@ extern dec route(
  * ```
  */
 extern dec sharedRoute(target: Operation);
-
-/**
- * Private decorators. Those are meant for internal use inside Http types only.
- */
-namespace Private {
-  extern dec plainData(target: TypeSpec.Reflection.Model);
-}

packages/http/lib/http.tsp

@@ -1,5 +1,6 @@
 import "../dist/src/index.js";
-import "./http-decorators.tsp";
+import "./decorators.tsp";
+import "./private.decorators.tsp";
 import "./auth.tsp";
 
 namespace TypeSpec.Http;
@@ -104,3 +105,18 @@ model ConflictResponse is Response<409>;
 model PlainData<Data> {
   ...Data;
 }
+
+@Private.httpFile
+model File {
+  contentType?: string;
+  filename?: string;
+  contents: bytes;
+}
+
+model HttpPartOptions {
+  /** Name of the part when using the array form. */
+  name?: string;
+}
+
+@Private.httpPart(Type, Options)
+model HttpPart<Type, Options extends valueof HttpPartOptions = #{}> {}

packages/http/lib/private.decorators.tsp

@@ -0,0 +1,14 @@
+import "../dist/src/private.decorators.js";
+
+/**
+ * Private decorators. Those are meant for internal use inside Http types only.
+ */
+namespace TypeSpec.Http.Private;
+
+extern dec plainData(target: TypeSpec.Reflection.Model);
+extern dec httpFile(target: TypeSpec.Reflection.Model);
+extern dec httpPart(
+  target: TypeSpec.Reflection.Model,
+  type: unknown,
+  options: valueof HttpPartOptions
+);