Multipart object and array-of-binary fields make the method return `HttpError::Config`

[iamralch]

A multipart/form-data body with a field that is a JSON object, or an array of files, generates a method that returns HttpError::Config before sending anything, so the operation can't be called:

let mut req = self.http_client.put(request_url);
return Err(
    HttpError::Config(
            "multipart field `metadata` must be binary or a scalar text field"
                .to_string(),
        )
        .into(),
);
// the rest is unreachable

The rest of the method is unreachable, so it also compiles with unreachable_code, unused_variables and unused_mut warnings.

Reproduce

spec.yaml:

openapi: 3.0.3
info:
  title: multipart repro
  version: "1"
paths:
  /scripts:
    put:
      operationId: uploadScript
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [metadata]
              properties:
                # A JSON object, sent as one part, as Workers script uploads do.
                metadata:
                  type: object
                  properties:
                    main_module: { type: string }
                files:
                  type: array
                  items: { type: string, format: binary }
            encoding:
              metadata:
                contentType: application/json
      responses:
        "200":
          description: ok

openapi-to-rust.toml:

[generator]
spec_path = "spec.yaml"
output_dir = "out"
module_name = "repro"

[features]
enable_async_client = true

With 0.19.0, upload_script returns the error above for files. With files removed, it returns it for metadata instead, so each of the two shapes is unsupported on its own.

Expected:

• an object field is serialized as JSON into one part, with the encoding.<field>.contentType from the document (application/json here), or application/json by default;
• an array of binary is sent as one part per item, under the same name.

Where it comes from

Cloudflare's document, where 13 operations take one of these, among them uploading a Worker (PUT /accounts/{account_id}/workers/scripts/{script_name}: metadata object and files array), writing a KV value with metadata, and uploading to Images. They are some of the most used operations in the API, so the client can't be used for them at all.

[iamralch]

Before writing code for this, here's how I'd fix it. I'd like to know whether it's a direction you'd take.

What fails today

Each multipart field becomes one part, encoded as bytes, base64 or text, and anything else returns HttpError::Config up front. encoding.<field>.contentType isn't read, so no part has a Content-Type. In Cloudflare's document, the 13 operations this blocks have three shapes:

Shape	Example	Operations
A JSON object field	Images metadata, Workers settings, KV metadata	5
An array of files	Workers files (the script's modules), Workers AI files	8
A field that is text or bytes	KV value (oneOf: [string, string/binary])	1

(The KV write has both a JSON field and a text-or-bytes field.)

Proposal

Follow OpenAPI's defaults for multipart:

1. Object fields are one JSON part, serialized with serde_json. Its Content-Type is encoding.<field>.contentType when that's a single media type, and application/json, the OpenAPI default for objects, otherwise.
2. A text-or-bytes union sends the branch it holds: a text part, or a bytes part.
3. Arrays are one part per item under the field's name. Two changes are needed for files:

   • Array items with format: binary are typed as String today (files: Vec<String>), not as the configured binary type. They'd use the binary strategy, as a single binary field does.

   • Each file needs its own filename and content type. Cloudflare's main module, for one, is worker.js as application/javascript+module. So items would be a small runtime type:

     pub struct MultipartFile {
         pub content: bytes::Bytes,
         pub file_name: Option<String>,
         pub content_type: Option<String>,
     }

     It has From<Bytes> and From<Vec<u8>>, so plain bytes still work. The other option I considered is extending *_with_multipart_filenames with indexed names (files[0]). It would avoid a new type, but it can't set a content type, and it's awkward to call.

4. A contentType that lists several types (Cloudflare writes application/javascript+module, text/javascript, …, application/wasm) is read as the set of allowed types, so the generator doesn't pick one. A MultipartFile's own content_type is used instead.

I'd split it into two PRs: 1 and 2, which are small and change no types, then 3, which adds MultipartFile and changes Vec<String> to Vec<MultipartFile>. That's breaking on paper, but none of those methods can be called today.

Not covered here: bodies whose part names are map keys, such as Cloudflare's Snippets (a file per name) and Workers assets upload (a part per hash), which are typed additionalProperties. They fail with a different error and seem worth a separate design.

One thing I haven't verified against Cloudflare

These rules send metadata as one JSON part, as Cloudflare's documented curl examples do, and each module as a part named files with the module's filename. Cloudflare's docs describe main_module as the name of "the part", while its TypeScript SDK sends files[] parts and metadata[main_module] fields. So I take it the API matches modules by filename and accepts more than one encoding. I haven't checked that with a live upload, and I'd do so before the second PR. It doesn't change the proposal, which follows OpenAPI rather than any one API.

Does this sound right to you, in particular MultipartFile and the split?

[lightsofapollo]

Thanks for writing this up before diving in, really appreciate it. Overall yes, this is the direction I'd take. Following OpenAPI's defaults rather than any one API's quirks is the right call, and the two-PR split makes sense.

A couple of things I'd change before you start on the second PR:

One way to name files, not two. *_with_multipart_filenames only shipped in 0.19.0 last week, and if MultipartFile lands for arrays only we end up with two different mechanisms depending on whether a field is a single file or a list of them. I'd rather go all in: use MultipartFile for every binary multipart field, single or array, and drop the *_with_multipart_filenames methods and builder setters in the same PR. We don't keep backwards compat around here, so don't worry about that. It also means per-part content type works everywhere, not just for arrays.

Respect the binary strategy. Single binary fields follow types.binary today (bytes / vec_u8 / string), and the 0.19 changelog calls out string mappings for filename overrides. Hard-coding content: bytes::Bytes would quietly ignore that config. Either have MultipartFile carry whatever that setting maps to, or decide that multipart always uses bytes and say so in the docs/changelog. I lean slightly toward following the config, but I'm open if you think it's more trouble than it's worth.

Small one: when encoding.<field>.contentType is a single media type, I'd apply it to any part, not just object parts (e.g. a lone binary field declared as image/png).

Agreed on leaving the map-keyed bodies (Snippets, assets upload) for a separate design. And yes, please do a real Workers upload before the second PR. Given the docs and the SDK disagree on how modules are matched, I'd like to know it actually works end to end.

Also, thanks for #90 through #92. Going through them now.

[lightsofapollo]

landed other prs- let me know if you don't end up picking this up I'll finish it

[iamralch]

I ran the live Workers upload before the second PR, in the shape it will generate: a metadata part as JSON, and one part per module, all named files, each with its own filename and application/javascript+module:

curl -X PUT ".../accounts/$ACCOUNT/workers/scripts/$NAME" \
  -F 'metadata={"main_module":"worker.js","compatibility_date":"2026-09-01"};type=application/json' \
  -F 'files=@worker.js;filename=worker.js;type=application/javascript+module' \
  -F 'files=@lib.js;filename=lib.js;type=application/javascript+module'

worker.js imports ./lib.js, so the upload only passes if Cloudflare finds the second module.

	Result
Upload as above	success: true, handlers ["fetch"]
Same, with lib.js sent as filename=other.js	10021: Uncaught Error: No such module "lib.js". imported from "worker.js"
GET the deployed Worker on workers.dev	hello from a second module

So Cloudflare matches modules by filename, not by part name, and takes all of them under the one name files. It also takes metadata as a single JSON part, which is what #94 sends now. The SDK's files[] naming is one encoding it accepts, not the only one.

That settles the design for the second PR: each file carries its own filename and content type (MultipartFile), and an array of files is one part per item under the field's name. I'll start on it on top of #94, and run the same upload through the generated client before opening it.

[iamralch]

Both halves are up:

• fix(client): send object multipart fields as JSON parts #94: objects as JSON parts, plus the declared contentType applied to any part
• fix(client): send multipart files and lists as parts of their own #96: MultipartFile for every binary field (following types.binary), lists sent one part per item, and *_with_multipart_filenames removed. It's built on fix(client): send object multipart fields as JSON parts #94, so merging fix(client): send object multipart fields as JSON parts #94 first is easiest. I'll rebase fix(client): send multipart files and lists as parts of their own #96 afterwards.

#96 includes an ignored live test, tests/cloudflare_workers_upload_live_test.rs. It uploads a two-module Worker through the client generated from the pinned Cloudflare spec. My run passed: the upload succeeded, and the control with the module renamed was rejected with No such module "lib.js".