FormData: throw when serializing an S3-backed entry instead of sending an empty part

docs/runtime/s3.mdx

@@ -603,6 +603,17 @@ Like `Bun.file()`, `S3File` extends [`Blob`](https://developer.mozilla.org/en-US
 
 Because `S3File` extends `Blob`, `S3File` instances work with `fetch()`, `Response`, and other web APIs that accept `Blob` instances.
 
+A `FormData` body is the exception. Bun builds a `FormData` body synchronously, and Bun can only download an S3 object asynchronously. When an entry is an S3 file, `new Response(formData)` and `new Request()` throw a `TypeError`, and `fetch()` rejects with one. To send the object, read its bytes first and append a `File`:
+
+```ts s3.ts icon="/icons/typescript.svg"
+const formData = new FormData();
+formData.append("file", new File([await s3file.bytes()], "123.json", { type: s3file.type }));
+
+await fetch("https://example.com/upload", { method: "POST", body: formData });
+```
+
+An empty slice, such as `s3file.slice(0, 0)`, has no bytes to download. Bun sends that entry as an empty part.
+
 ### Partial reads with `slice`
 
 To read a partial range of a file, use the `slice` method.

packages/bun-types/s3.d.ts

@@ -473,6 +473,13 @@ declare module "bun" {
    * Represents a file in an S3-compatible storage service.
    * Extends the Blob interface for compatibility with web APIs.
    *
+   * Bun downloads the object only when you read it. Bun builds a `FormData`
+   * body synchronously. When an entry is an `S3File`, `new Response(formData)`
+   * and `new Request()` throw a `TypeError`, and `fetch()` rejects with one.
+   * Read the bytes first and append a `File`:
+   * `new File([await file.bytes()], "report.csv", { type: file.type })`.
+   * Bun sends an empty slice (`file.slice(0, 0)`) as an empty part.
+   *
    * @category Cloud Storage
    */
   interface S3File extends Blob {

src/runtime/server/RequestContext.rs

@@ -2655,7 +2655,7 @@ where
                 // (here, `blob`) may still be live across it. Nothing is written
                 // to the socket in between, so the wire output is unchanged.
                 let blob_size = if shim::blob_is_s3(blob) {
-                    // Match the body GET sends (`render_bytes`). `resolve_size()` would set the blob's size to 0.
+                    // Match the body GET sends (`render_bytes`): no bytes. `size` is unknown, or the window of a slice.
                     blob.shared_view().len() as BlobSizeType
                 } else {
                     blob.resolve_size();

src/runtime/webcore/Blob.rs

@@ -802,7 +802,7 @@ impl BlobExt for Blob {
         let mut context = FormDataContext {
             joiner: bun_core::string_joiner::StringJoiner::default(),
             boundary,
-            failed: false,
+            failure: None,
             global_this,
         };
         // Size the node list up front: a file entry pushes at most 13 slices, a
@@ -849,7 +849,7 @@ impl BlobExt for Blob {
         unsafe extern "C" {
             // `this` is the `&mut DOMFormData` param (coerced); `ctx`/`cb` are
             // stored opaquely and only used synchronously. Module-private with
-            // one call site below — no caller-side precondition remains. Kept
+            // two call sites below — no caller-side precondition remains. Kept
             // `*mut` (not `&mut`) to match the `bun_jsc` decl and avoid
             // `clashing_extern_declarations`.
             safe fn DOMFormData__forEach(
@@ -868,14 +868,54 @@ impl BlobExt for Blob {
                 ),
             );
         }
+        /// A second walk, so that the first one keeps no entry name for this.
+        #[cold]
+        fn throw_for_s3_entry(
+            global_this: &JSGlobalObject,
+            form_data: &mut jsc::DOMFormData,
+            entry: *const Blob,
+        ) {
+            struct Find {
+                entry: *const Blob,
+                name: Option<Vec<u8>>,
+            }
+            extern "C" fn find_thunk(
+                ctx_ptr: *mut c_void,
+                name: *mut EncodedSlice,
+                value_ptr: *mut c_void,
+                _filename: *mut EncodedSlice,
+                is_blob: u8,
+            ) {
+                // SAFETY: `ctx_ptr` is the `&mut Find` passed below.
+                let find = unsafe { bun_ptr::callback_ctx::<Find>(ctx_ptr) };
+                if is_blob != 0
+                    && find.name.is_none()
+                    && core::ptr::eq(value_ptr.cast::<Blob>(), find.entry)
+                {
+                    // SAFETY: `name` is always a valid non-null `*EncodedSlice` for this callback.
+                    find.name = Some(unsafe { *name }.to_utf8().into_vec());
+                }
+            }
+            let mut find = Find { entry, name: None };
+            DOMFormData__forEach(form_data, (&raw mut find).cast::<c_void>(), find_thunk);
+            debug_assert!(find.name.is_some(), "the first walk met this entry");
+            let _ = global_this.throw_type_error(format_args!(
+                "FormData entry {} is an S3 file, which cannot be read while the body is serialized. Pass its bytes instead: new File([await s3file.bytes()], s3file.name, {{ type: s3file.type }})",
+                bun_core::fmt::quote(find.name.as_deref().unwrap_or_default()),
+            ));
+        }
+
         // C++ invokes the callback synchronously and does not retain `ctx`/`cb`
         // past this call.
         DOMFormData__forEach(
             form_data,
             (&raw mut context).cast::<c_void>(),
             for_each_thunk,
         );
-        if context.failed {
+        if let Some(failure) = context.failure {
+            if let FormDataFailure::S3Entry(entry) = failure {
+                throw_for_s3_entry(global_this, form_data, entry);
+            }
             // Drop the joiner (Drop runs StringJoiner::deinit) so every
             // heap-owned slice already pushed — escaped names, non-ASCII
             // conversions, NodeFS read_file result buffers — is freed.
@@ -2063,7 +2103,8 @@ impl BlobExt for Blob {
                 }
                 self.size.set(0);
             }
-            store::DataTag::S3 => self.size.set(0),
+            // An S3 object has no size before the download: there is nothing to resolve.
+            store::DataTag::S3 => {}
         }
     }
 
@@ -2106,7 +2147,7 @@ impl BlobExt for Blob {
                 }
                 (self.offset.get(), 0)
             }
-            store::DataTag::S3 => (self.offset.get(), 0),
+            store::DataTag::S3 => (self.offset.get(), self.size.get()),
         }
     }
     fn constructor(
@@ -3450,10 +3491,19 @@ where
 struct FormDataContext<'a> {
     joiner: StringJoiner<'a>,
     boundary: &'a [u8], // borrowed; outlives the joiner
-    failed: bool,
+    failure: Option<FormDataFailure>,
     global_this: &'a JSGlobalObject,
 }
 
+/// Why `FormDataContext::on_entry` stopped serializing.
+#[derive(Clone, Copy)]
+enum FormDataFailure {
+    /// `on_entry` threw.
+    Thrown,
+    /// An S3 entry, known by the address of its Blob (compared, never read). `from_dom_form_data` throws for it after the walk.
+    S3Entry(*const Blob),
+}
+
 /// Which piece of a `multipart/form-data` entry a string is, selecting the
 /// transforms the WHATWG "multipart/form-data encoding algorithm" applies to
 /// it: <https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#multipart-form-data>
@@ -3541,7 +3591,7 @@ impl FormDataContext<'_> {
     }
 
     fn on_entry(&mut self, name: EncodedSlice, entry: FormDataEntry<'_>) {
-        if self.failed {
+        if self.failure.is_some() {
             return;
         }
         // Copy the borrowed refs out first (disjoint-field reads) so the
@@ -3594,8 +3644,11 @@ impl FormDataContext<'_> {
                         .expect("infallible: store present");
                     match &store.data {
                         store::Data::S3(_) => {
-                            // TODO: s3
-                            // we need to make this async and use download/downloadSlice
+                            // An empty window (`slice(n, n)`) is an empty part.
+                            if blob.size.get() != 0 {
+                                self.failure =
+                                    Some(FormDataFailure::S3Entry(core::ptr::from_ref(blob)));
+                            }
                         }
                         store::Data::File(file) => {
                             // TODO: make this async + lazy
@@ -3612,7 +3665,7 @@ impl FormDataContext<'_> {
                             let res = node_fs.read_file(&rf_args, crate::node::fs::Flavor::Sync);
                             match res {
                                 Err(err) => {
-                                    self.failed = true;
+                                    self.failure = Some(FormDataFailure::Thrown);
                                     let js_err = err.to_js(global_this);
                                     let _ = global_this.throw_value(js_err);
                                 }

src/runtime/webcore/Body.rs

@@ -741,7 +741,7 @@ impl Value {
         }
     }
 
-    /// `None` for a file that does not exist or is not seekable.
+    /// `None` for a file that does not exist or is not seekable, and for an S3 object that is not a slice.
     pub(crate) fn known_size(&mut self) -> Option<usize> {
         match self.size() {
             u64::MAX => None,

test/js/bun/s3/s3.test.ts

@@ -1,10 +1,11 @@
 import type { S3File, S3Options } from "bun";
 import { S3Client, s3 as defaultS3, file, randomUUIDv7 } from "bun";
-import { afterAll, describe, expect, it } from "bun:test";
+import { serialize } from "bun:jsc";
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
 import { createHash, createHmac, randomUUID } from "crypto";
 import { bunEnv, bunExe, getSecret, isCI, tempDir, tempDirWithFiles } from "harness";
 import path from "path";
-import { spawnServer } from "s3-server";
+import { serve, spawnServer, type S3Server } from "s3-server";
 const s3 = (...args: Parameters<typeof defaultS3.file>) => defaultS3.file(...args);
 const S3 = (...args) => new S3Client(...args);
 
@@ -2170,3 +2171,119 @@ describe("presigned url signature", () => {
     }
   });
 });
+
+// The size of an S3 object is not known before the download. A call that asks
+// for the size has to leave it unknown. A file whose size became 0 asked for one
+// byte (`Range: bytes=0-0`) on each later read, and a copy of it stored that byte.
+describe("an S3 file after a call that asks for its size", () => {
+  const payload = Buffer.alloc(100, "0123456789").toString();
+  // In this process, because only this server has a log of its requests.
+  let server: S3Server;
+  let client: S3Client;
+  beforeAll(() => {
+    server = serve({ buckets: ["bucket"] });
+    client = new S3Client(server.clientOptions("bucket"));
+  });
+  afterAll(() => server.stop());
+
+  /** Stores the payload under a new key. */
+  async function store() {
+    const key = randomUUIDv7();
+    await client.write(key, payload);
+    return key;
+  }
+  /** Each request for the key so far, as `[operation, Range header]`. */
+  const requests = (key: string) =>
+    server.requests
+      .filter(request => request.key === key)
+      .map(request => [request.operation, request.headers.get("range")]);
+
+  /** Makes the call. Whether it throws is not the subject of these tests: the file afterwards is. */
+  async function attempt(call: () => unknown) {
+    try {
+      await call();
+    } catch {}
+  }
+
+  /** Reads the blob and copies it, in each way. */
+  async function readAndCopy(blob: Blob) {
+    using dir = tempDir("s3-file-size", {});
+    const s3Copy = client.file(randomUUIDv7());
+    const localCopy = Bun.file(path.join(String(dir), "copy"));
+    return {
+      size: blob.size,
+      text: await blob.text(),
+      stream: await Bun.readableStreamToText(blob.stream()),
+      slice: await blob.slice(10, 20).text(),
+      s3Copy: [await s3Copy.write(blob), await s3Copy.text()],
+      localCopy: [await Bun.write(localCopy, blob), await localCopy.text()],
+    };
+  }
+  const whole = {
+    size: NaN,
+    text: payload,
+    stream: payload,
+    slice: payload.slice(10, 20),
+    s3Copy: [100, payload],
+    localCopy: [100, payload],
+  };
+  // One request for each read and each copy of `readAndCopy`. Only the slice has a Range header.
+  const requestsOfWhole = [
+    ["GetObject", null],
+    ["GetObject", null],
+    ["GetObject", "bytes=10-19"],
+    ["GetObject", null],
+    ["GetObject", null],
+  ];
+
+  const calls: Record<string, (file: S3File) => unknown> = {
+    "expect().toHaveLength()": file => expect(file).toHaveLength(0),
+    "expect().toBeEmpty()": file => expect(file).toBeEmpty(),
+    "structuredClone()": file => structuredClone(file),
+    "MessagePort.postMessage()": file => {
+      const { port1, port2 } = new MessageChannel();
+      try {
+        port1.postMessage(file);
+      } finally {
+        port1.close();
+        port2.close();
+      }
+    },
+    "serialize() of bun:jsc": file => serialize(file),
+  };
+  for (const [name, call] of Object.entries(calls)) {
+    it.concurrent(`${name}, two times`, async () => {
+      const key = await store();
+      const file = client.file(key);
+      await attempt(() => call(file));
+      await attempt(() => call(file));
+      const before = requests(key);
+      expect({ before, ...(await readAndCopy(file)), requests: requests(key).slice(before.length) }).toEqual({
+        before: [["PutObject", null]],
+        ...whole,
+        requests: requestsOfWhole,
+      });
+    });
+  }
+
+  it.concurrent("a FormData body, for the entry that the FormData holds", async () => {
+    const key = await store();
+    const form = new FormData();
+    form.append("file", client.file(key));
+    await attempt(() => new Response(form).arrayBuffer());
+    const before = requests(key);
+    const entry = form.get("file") as Blob;
+    expect({ before, ...(await readAndCopy(entry)), requests: requests(key).slice(before.length) }).toEqual({
+      before: [["PutObject", null]],
+      ...whole,
+      requests: requestsOfWhole,
+    });
+  });
+
+  it.concurrent("expect() does not take the unknown length for 0", async () => {
+    const file = client.file(await store());
+    expect(() => expect(file).toHaveLength(0)).toThrow("Received length");
+    expect(() => expect(file).toBeEmpty()).toThrow("Expected value to be empty");
+    expect(file.slice(10, 30)).toHaveLength(20);
+  });
+});