@typespec/http 0.68.0-dev.6 → 0.68.0-dev.8

package/lib/main.tsp

@@ -106,11 +106,154 @@ model PlainData<Data> {
   ...Data;
 }
 
+/**
+ * A file in an HTTP request, response, or multipart payload.
+ *
+ * Files have a special meaning that the HTTP library understands. When the body of an HTTP request, response,
+ * or multipart payload is _effectively_ an instance of `TypeSpec.Http.File` or any type that extends it, the
+ * operation is treated as a file upload or download.
+ *
+ * When using file bodies, the fields of the file model are defined to come from particular locations by default:
+ *
+ * - `contentType`: The `Content-Type` header of the request, response, or multipart payload (CANNOT be overridden or changed).
+ * - `contents`: The body of the request, response, or multipart payload (CANNOT be overridden or changed).
+ * - `filename`: The `filename` parameter value of the `Content-Disposition` header of the response or multipart payload
+ *   (MAY be overridden or changed).
+ *
+ * A File may be used as a normal structured JSON object in a request or response, if the request specifies an explicit
+ * `Content-Type` header. In this case, the entire File model is serialized as if it were any other model. In a JSON payload,
+ * it will have a structure like:
+ *
+ * ```
+ * {
+ *   "contentType": <string?>,
+ *   "filename": <string?>,
+ *   "contents": <string, base64>
+ * }
+ * ```
+ *
+ * The `contentType` _within_ the file defines what media types the data inside the file can be, but if the specification
+ * defines a `Content-Type` for the payload as HTTP metadata, that `Content-Type` metadata defines _how the file is
+ * serialized_. See the examples below for more information.
+ *
+ * NOTE: The `filename` and `contentType` fields are optional. Furthermore, the default location of `filename`
+ * (`Content-Disposition: <disposition>; filename=<filename>`) is only valid in HTTP responses and multipart payloads. If
+ * you wish to send the `filename` in a request, you must use HTTP metadata decorators to describe the location of the
+ * `filename` field. You can combine the metadata decorators with `@visibility` to control when the `filename` location
+ * is overridden, as shown in the examples below.
+ *
+ * @template ContentType The allowed media (MIME) types of the file contents.
+ * @template Contents The type of the file contents. This can be `string`, `bytes`, or any scalar that extends them.
+ *
+ * @example
+ * ```tsp
+ * // Download a file
+ * @get op download(): File;
+ *
+ * // Upload a file
+ * @post op upload(@bodyRoot file: File): void;
+ * ```
+ *
+ * @example
+ * ```tsp
+ * // Upload and download files in a multipart payload
+ * op multipartFormDataUpload(
+ *   @multipartBody fields: {
+ *     files: HttpPart<File>[];
+ *   },
+ * ): void;
+ *
+ * op multipartFormDataDownload(): {
+ *   @multipartBody formFields: {
+ *     files: HttpPart<File>[];
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * ```tsp
+ * // Declare a custom type of text file, where the filename goes in the path
+ * // in requests.
+ * model SpecFile extends File<"application/json" | "application/yaml", string> {
+ *   // Provide a header that contains the name of the file when created or updated
+ *   @header("x-filename")
+ *   @path filename: string;
+ * }
+ *
+ * @get op downloadSpec(@path name: string): SpecFile;
+ *
+ * @post op uploadSpec(@bodyRoot spec: SpecFile): void;
+ * ```
+ *
+ * @example
+ * ```tsp
+ * // Declare a custom type of binary file
+ * model ImageFile extends File {
+ *   contentType: "image/png" | "image/jpeg";
+ *   @path filename: string;
+ * }
+ *
+ * @get op downloadImage(@path name: string): ImageFile;
+ *
+ * @post op uploadImage(@bodyRoot image: ImageFile): void;
+ * ```
+ *
+ * @example
+ * ```tsp
+ * // Use a File as a structured JSON object. The HTTP library will warn you that the File will be serialized as JSON,
+ * // so you should suppress the warning if it's really what you want instead of a binary file upload/download.
+ *
+ * // The response body is a JSON object like `{"contentType":<string?>,"filename":<string?>,"contents":<string>}`
+ * @get op downloadTextFileJson(): {
+ *   @header contentType: "application/json",
+ *   @body file: File<"text/plain", string>,
+ * };
+ *
+ * // The request body is a JSON object like `{"contentType":<string?>,"filename":<string?>,"contents":<base64>}`
+ * @post op uploadBinaryFileJson(
+ *   @header contentType: "application/json",
+ *   @body file: File<"image/png", bytes>,
+ * ): void;
+ *
+ */
+@summary("A file in an HTTP request, response, or multipart payload.")
 @Private.httpFile
-model File {
-  contentType?: string;
+model File<ContentType extends string = string, Contents extends bytes | string = bytes> {
+  /**
+   * The allowed media (MIME) types of the file contents.
+   *
+   * In file bodies, this value comes from the `Content-Type` header of the request or response. In JSON bodies,
+   * this value is serialized as a field in the response.
+   *
+   * NOTE: this is not _necessarily_ the same as the `Content-Type` header of the request or response, but
+   * it will be for file bodies. It may be different if the file is serialized as a JSON object. It always refers to the
+   * _contents_ of the file, and not necessarily the way the file itself is transmitted or serialized.
+   */
+  @summary("The allowed media (MIME) types of the file contents.")
+  contentType?: ContentType;
+
+  /**
+   * The name of the file, if any.
+   *
+   * In file bodies, this value comes from the `filename` parameter of the `Content-Disposition` header of the response
+   * or multipart payload. In JSON bodies, this value is serialized as a field in the response.
+   *
+   * NOTE: By default, `filename` cannot be sent in request payloads and can only be sent in responses and multipart
+   * payloads, as the `Content-Disposition` header is not valid in requests. If you want to send the `filename` in a request,
+   * you must extend the `File` model and override the `filename` property with a different location defined by HTTP metadata
+   * decorators.
+   */
+  @summary("The name of the file, if any.")
   filename?: string;
-  contents: bytes;
+
+  /**
+   * The contents of the file.
+   *
+   * In file bodies, this value comes from the body of the request, response, or multipart payload. In JSON bodies,
+   * this value is serialized as a field in the response.
+   */
+  @summary("The contents of the file.")
+  contents: Contents;
 }
 
 model HttpPartOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/http",
-  "version": "0.68.0-dev.6",
+  "version": "0.68.0-dev.8",
   "author": "Microsoft Corporation",
   "description": "TypeSpec HTTP protocol binding",
   "homepage": "https://github.com/microsoft/typespec",