Bun.serve direct streams: flush on controller.close(), end the response once, call cancel() only on a client abort

docs/runtime/streams.mdx

@@ -64,15 +64,24 @@ const stream = new ReadableStream({
   pull(controller) {
     controller.write("hello");
     controller.write("world");
+    controller.close();
   },
 });
 ```
 
 When using a direct `ReadableStream`, the destination handles all chunk queueing. The destination receives the bytes you pass to `controller.write()`. When the stream is read from JavaScript, Bun buffers the writes and delivers them as `Uint8Array` chunks (strings are UTF-8 encoded).
 
+### Ending the stream
+
+Call `controller.close()` (or `controller.end()`) once everything is written. Every destination flushes what it has buffered and finishes at that point. `controller.close(error)` fails the stream instead: nothing more is flushed and the consumer rejects with `error`.
+
+A destination that takes the whole body (`Bun.serve`, `fetch`, `Bun.write`, `Bun.spawn` stdin, `.text()`, and so on) calls `pull()` once. If it returns a promise, the stream stays open while that promise is pending and ends when it resolves, as if `pull()` had called `controller.close()` last; if it rejects, the stream errors with that reason. A `pull()` that returns without a promise and without closing keeps the stream open until something calls `controller.close()`, so you can hold on to the controller and write from events.
+
+When the stream is read through a reader (`getReader()`, `for await`, `pipeTo()`, `tee()`), `pull()` is a demand signal instead: it is called again for a later read, never while a previous call's promise is still pending, until `controller.close()`.
+
 ### Handling backpressure
 
-`controller.write()` returns the number of bytes written, or a **pending `Promise<number>`** when the destination's internal buffer is full (for example, a slow HTTP client). The chunk is accepted either way. The promise resolves once the destination has drained, so `await`ing the result is enough:
+`controller.write()` returns the number of bytes written, or a **pending `Promise<number>`** when the destination's internal buffer is full (for example, a slow HTTP client). The chunk is accepted either way. Once the destination has gone away (for example the HTTP client disconnected), `write()` returns `0`. The promise resolves once the destination has drained, so `await`ing the result is enough:
 
 ```ts
 const stream = new ReadableStream({

mordant-baseline.toml

@@ -140,7 +140,7 @@
 "unused_pub:src/io/ParentDeathWatchdog.rs" = 1
 "unused_pub:src/io/PipeWriter.rs" = 2
 "unused_pub:src/jsc/bindgen.rs" = 6
-"unused_pub:src/jsc/host_fn.rs" = 1
+"unused_pub:src/jsc/host_fn.rs" = 2
 "unused_pub:src/jsc/lib.rs" = 1
 "unused_pub:src/jsc/webcore_types.rs" = 2
 "unused_pub:src/libarchive/lib.rs" = 1

packages/bun-types/bun.d.ts

@@ -579,6 +579,19 @@ declare module "bun" {
 
   interface DirectUnderlyingSource<R = any> {
     cancel?: UnderlyingSourceCancelCallback;
+    /**
+     * Write the stream's data with `controller.write()` (await it for
+     * backpressure) and finish with `controller.close()`.
+     *
+     * A destination that takes the whole body (`Bun.serve`, `Bun.write`,
+     * `.text()`, ...) calls `pull()` once. If it returns a promise, the stream
+     * stays open while it is pending, ends when it resolves, and errors if it
+     * rejects. If it returns synchronously without closing, the stream stays
+     * open until `controller.close()` is called.
+     *
+     * A reader (`getReader()`, `for await`, `pipeTo()`) calls `pull()` again
+     * for a later read, once the previous call has settled.
+     */
     pull: (controller: ReadableStreamDirectController) => void | PromiseLike<void>;
     type: "direct";
   }

packages/bun-types/globals.d.ts

@@ -727,6 +727,11 @@ interface ReadableStreamDefaultController<R = any> {
 }
 
 interface ReadableStreamDirectController {
+  /**
+   * Finish the stream. With no argument this flushes buffered bytes and ends,
+   * like {@link end}. With an `error`, the stream fails: buffered bytes are
+   * dropped and the consumer rejects with `error`.
+   */
   close(error?: Error): void;
   /**
    * Write a chunk directly to the destination.
@@ -741,6 +746,9 @@ interface ReadableStreamDirectController {
    *
    * The promise resolves once the destination has drained.
    * `await controller.flush(true)` is equivalent.
+   *
+   * Returns `0` once the destination has gone away (for example, the HTTP
+   * client disconnected).
    */
   write(data: Bun.BufferSource | ArrayBuffer | string): number | Promise<number>;
   end(): number | Promise<number>;