|
| 1 | +// Copyright (c) Microsoft Corporation. |
| 2 | +// Licensed under the MIT license. |
| 3 | + |
| 4 | +import { |
| 5 | + BodyPart, |
| 6 | + MultipartRequestBody, |
| 7 | + RawHttpHeadersInput, |
| 8 | + RestError, |
| 9 | + createHttpHeaders, |
| 10 | +} from "@azure/core-rest-pipeline"; |
| 11 | +import { stringToUint8Array } from "@azure/core-util"; |
| 12 | +import { isBinaryBody } from "./helpers/isBinaryBody.js"; |
| 13 | + |
| 14 | +/** |
| 15 | + * Describes a single part in a multipart body. |
| 16 | + */ |
| 17 | +export interface PartDescriptor { |
| 18 | + /** |
| 19 | + * Content type of this part. If set, this value will be used to set the Content-Type MIME header for this part, although explicitly |
| 20 | + * setting the Content-Type header in the headers bag will override this value. If set to `null`, no content type will be inferred from |
| 21 | + * the body field. Otherwise, the value of the Content-Type MIME header will be inferred based on the type of the body. |
| 22 | + */ |
| 23 | + contentType?: string | null; |
| 24 | + |
| 25 | + /** |
| 26 | + * The disposition type of this part (for example, "form-data" for parts making up a multipart/form-data request). If set, this value |
| 27 | + * will be used to set the Content-Disposition MIME header for this part, in addition to the `name` and `filename` properties. |
| 28 | + * If the `name` or `filename` properties are set while `dispositionType` is left undefined, `dispositionType` will default to "form-data". |
| 29 | + * |
| 30 | + * Explicitly setting the Content-Disposition header in the headers bag will override this value. |
| 31 | + */ |
| 32 | + dispositionType?: string; |
| 33 | + |
| 34 | + /** |
| 35 | + * The field name associated with this part. This value will be used to construct the Content-Disposition header, |
| 36 | + * along with the `dispositionType` and `filename` properties, if the header has not been set in the `headers` bag. |
| 37 | + */ |
| 38 | + name?: string; |
| 39 | + |
| 40 | + /** |
| 41 | + * The file name of the content if it is a file. This value will be used to construct the Content-Disposition header, |
| 42 | + * along with the `dispositionType` and `name` properties, if the header has not been set in the `headers` bag. |
| 43 | + */ |
| 44 | + filename?: string; |
| 45 | + |
| 46 | + /** |
| 47 | + * The multipart headers for this part of the multipart body. Values of the Content-Type and Content-Disposition headers set in the headers bag |
| 48 | + * will take precedence over those computed from the request body or the contentType, dispositionType, name, and filename fields on this object. |
| 49 | + */ |
| 50 | + headers?: RawHttpHeadersInput; |
| 51 | + |
| 52 | + /** |
| 53 | + * The body of this part of the multipart request. |
| 54 | + */ |
| 55 | + body?: unknown; |
| 56 | +} |
| 57 | + |
| 58 | +type MultipartBodyType = BodyPart["body"]; |
| 59 | + |
| 60 | +type HeaderValue = RawHttpHeadersInput[string]; |
| 61 | + |
| 62 | +/** |
| 63 | + * Get value of a header in the part descriptor ignoring case |
| 64 | + */ |
| 65 | +function getHeaderValue(descriptor: PartDescriptor, headerName: string): HeaderValue | undefined { |
| 66 | + if (descriptor.headers) { |
| 67 | + const actualHeaderName = Object.keys(descriptor.headers).find( |
| 68 | + (x) => x.toLowerCase() === headerName.toLowerCase(), |
| 69 | + ); |
| 70 | + if (actualHeaderName) { |
| 71 | + return descriptor.headers[actualHeaderName]; |
| 72 | + } |
| 73 | + } |
| 74 | + |
| 75 | + return undefined; |
| 76 | +} |
| 77 | + |
| 78 | +function getPartContentType(descriptor: PartDescriptor): HeaderValue | undefined { |
| 79 | + const contentTypeHeader = getHeaderValue(descriptor, "content-type"); |
| 80 | + if (contentTypeHeader) { |
| 81 | + return contentTypeHeader; |
| 82 | + } |
| 83 | + |
| 84 | + // Special value of null means content type is to be omitted |
| 85 | + if (descriptor.contentType === null) { |
| 86 | + return undefined; |
| 87 | + } |
| 88 | + |
| 89 | + if (descriptor.contentType) { |
| 90 | + return descriptor.contentType; |
| 91 | + } |
| 92 | + |
| 93 | + const { body } = descriptor; |
| 94 | + |
| 95 | + if (body === null || body === undefined) { |
| 96 | + return undefined; |
| 97 | + } |
| 98 | + |
| 99 | + if (typeof body === "string" || typeof body === "number" || typeof body === "boolean") { |
| 100 | + return "text/plain; charset=UTF-8"; |
| 101 | + } |
| 102 | + |
| 103 | + if (body instanceof Blob) { |
| 104 | + return body.type || "application/octet-stream"; |
| 105 | + } |
| 106 | + |
| 107 | + if (isBinaryBody(body)) { |
| 108 | + return "application/octet-stream"; |
| 109 | + } |
| 110 | + |
| 111 | + // arbitrary non-text object -> generic JSON content type by default. We will try to JSON.stringify the body. |
| 112 | + return "application/json; charset=UTF-8"; |
| 113 | +} |
| 114 | + |
| 115 | +/** |
| 116 | + * Enclose value in quotes and escape special characters, for use in the Content-Disposition header |
| 117 | + */ |
| 118 | +function escapeDispositionField(value: string): string { |
| 119 | + return JSON.stringify(value); |
| 120 | +} |
| 121 | + |
| 122 | +function getContentDisposition(descriptor: PartDescriptor): HeaderValue | undefined { |
| 123 | + const contentDispositionHeader = getHeaderValue(descriptor, "content-disposition"); |
| 124 | + if (contentDispositionHeader) { |
| 125 | + return contentDispositionHeader; |
| 126 | + } |
| 127 | + |
| 128 | + if ( |
| 129 | + descriptor.dispositionType === undefined && |
| 130 | + descriptor.name === undefined && |
| 131 | + descriptor.filename === undefined |
| 132 | + ) { |
| 133 | + return undefined; |
| 134 | + } |
| 135 | + |
| 136 | + const dispositionType = descriptor.dispositionType ?? "form-data"; |
| 137 | + |
| 138 | + let disposition = dispositionType; |
| 139 | + if (descriptor.name) { |
| 140 | + disposition += `; name=${escapeDispositionField(descriptor.name)}`; |
| 141 | + } |
| 142 | + |
| 143 | + let filename: string | undefined = undefined; |
| 144 | + if (descriptor.filename) { |
| 145 | + filename = descriptor.filename; |
| 146 | + } else if (typeof File !== "undefined" && descriptor.body instanceof File) { |
| 147 | + const filenameFromFile = (descriptor.body as File).name; |
| 148 | + if (filenameFromFile !== "") { |
| 149 | + filename = filenameFromFile; |
| 150 | + } |
| 151 | + } |
| 152 | + |
| 153 | + if (filename) { |
| 154 | + disposition += `; filename=${escapeDispositionField(filename)}`; |
| 155 | + } |
| 156 | + |
| 157 | + return disposition; |
| 158 | +} |
| 159 | + |
| 160 | +function normalizeBody(body?: unknown, contentType?: HeaderValue): MultipartBodyType { |
| 161 | + if (body === undefined) { |
| 162 | + // zero-length body |
| 163 | + return new Uint8Array([]); |
| 164 | + } |
| 165 | + |
| 166 | + // binary and primitives should go straight on the wire regardless of content type |
| 167 | + if (isBinaryBody(body)) { |
| 168 | + return body; |
| 169 | + } |
| 170 | + if (typeof body === "string" || typeof body === "number" || typeof body === "boolean") { |
| 171 | + return stringToUint8Array(String(body), "utf-8"); |
| 172 | + } |
| 173 | + |
| 174 | + // stringify objects for JSON-ish content types e.g. application/json, application/merge-patch+json, application/vnd.oci.manifest.v1+json, application.json; charset=UTF-8 |
| 175 | + if (contentType && /application\/(.+\+)?json(;.+)?/i.test(String(contentType))) { |
| 176 | + return stringToUint8Array(JSON.stringify(body), "utf-8"); |
| 177 | + } |
| 178 | + |
| 179 | + throw new RestError(`Unsupported body/content-type combination: ${body}, ${contentType}`); |
| 180 | +} |
| 181 | + |
| 182 | +export function buildBodyPart(descriptor: PartDescriptor): BodyPart { |
| 183 | + const contentType = getPartContentType(descriptor); |
| 184 | + const contentDisposition = getContentDisposition(descriptor); |
| 185 | + const headers = createHttpHeaders(descriptor.headers ?? {}); |
| 186 | + |
| 187 | + if (contentType) { |
| 188 | + headers.set("content-type", contentType); |
| 189 | + } |
| 190 | + if (contentDisposition) { |
| 191 | + headers.set("content-disposition", contentDisposition); |
| 192 | + } |
| 193 | + |
| 194 | + const body = normalizeBody(descriptor.body, contentType); |
| 195 | + |
| 196 | + return { |
| 197 | + headers, |
| 198 | + body, |
| 199 | + }; |
| 200 | +} |
| 201 | + |
| 202 | +export function buildMultipartBody(parts: PartDescriptor[]): MultipartRequestBody { |
| 203 | + return { parts: parts.map(buildBodyPart) }; |
| 204 | +} |
0 commit comments