feat: add multipart range requests

.changeset/multipart-range-requests.md

@@ -0,0 +1,5 @@
+---
+"webpack-dev-middleware": minor
+---
+
+Added support for `multipart/byteranges` responses. A `Range` header with several separate ranges now returns a `206` with one part per range instead of the whole file. Requests with more than 200 ranges, or ranges that cover the whole file, still get a normal `200`.

.cspell.json

@@ -3,6 +3,7 @@
   "language": "en,en-gb",
   "words": [
     "apos",
+    "byteranges",
     "cachable",
     "cexoso",
     "commitlint",

src/middleware.js

@@ -3,6 +3,7 @@ const querystring = require("node:querystring");
 const { finished } = require("node:stream");
 
 const {
+  createMultipartBody,
   createReadStreamOrReadFile,
   destroyStream,
   escapeHtml,
@@ -337,6 +338,10 @@ async function getFilenameFromUrl(context, url) {
 
 const CACHE_CONTROL_NO_CACHE_REGEXP = /(?:^|,)\s*?no-cache\s*?(?:,|$)/;
 
+// More ranges than this, and the response stays a regular `200`: no cache or
+// client can use that many parts, and the boundary bookkeeping outweighs them.
+const MAX_MULTIPART_RANGES = 200;
+
 /** @type {Record<number, string>} */
 const statuses = {
   400: "Bad Request",
@@ -917,7 +922,7 @@ function wrapper(context) {
       /** @type {number} */
       let end;
 
-      /** @type {undefined | Buffer | ReadStream} */
+      /** @type {undefined | Buffer | ReadStream | import("node:stream").Readable} */
       let bufferOrStream;
       /** @type {number | undefined} */
       let byteLength;
@@ -1060,9 +1065,43 @@ function wrapper(context) {
             "A malformed 'Range' header was provided. A regular response will be sent for this request.",
           );
         } else if (parsedRanges.length > 1) {
-          context.logger.error(
-            "A 'Range' header with multiple ranges was provided. Multiple ranges are not supported, so a regular response will be sent for this request.",
+          const ranges = /** @type {import("range-parser").Ranges} */ (
+            parsedRanges
           );
+
+          let shouldUseMultipart = true;
+
+          if (ranges.length > MAX_MULTIPART_RANGES) {
+            shouldUseMultipart = false;
+          } else {
+            let covered = 0;
+            for (const range of ranges) {
+              covered += range.end - range.start + 1;
+            }
+            if (covered >= size) {
+              shouldUseMultipart = false;
+            }
+          }
+
+          if (shouldUseMultipart) {
+            const contentType = context.mimeTypes.contentType(filename);
+            const multipartResult = createMultipartBody({
+              filename,
+              outputFileSystem: extra.outputFileSystem,
+              ranges,
+              size,
+              contentType,
+            });
+            setStatusCode(res, 206);
+            setResponseHeader(
+              res,
+              "Content-Type",
+              `multipart/byteranges; boundary=${multipartResult.boundary}`,
+            );
+            isPartialContent = true;
+            bufferOrStream = multipartResult.bufferOrStream;
+            byteLength = multipartResult.byteLength;
+          }
         }
 
         if (parsedRanges !== -2 && parsedRanges.length === 1) {
@@ -1106,7 +1145,7 @@ function wrapper(context) {
           context.options.modifyResponseData(
             req,
             res,
-            bufferOrStream,
+            /** @type {Buffer | ReadStream} */ (bufferOrStream),
             /** @type {number} */
             (byteLength),
           ));

src/utils.js

@@ -11,6 +11,7 @@
 
 const crypto = require("node:crypto");
 const path = require("node:path");
+const { Readable } = require("node:stream");
 
 /** @typedef {import("./index").IncomingMessage} IncomingMessage */
 /** @typedef {import("./index").ServerResponse} ServerResponse */
@@ -566,6 +567,108 @@ function destroyStream(stream, suppress) {
   }
 }
 
+// A `Range` header with several ranges is answered with one part per range
+// rather than with the whole file. Whether that applies is the caller's
+// decision: ranges that cover the whole file, and more ranges than a cache or
+// a client can use, stay a regular response instead.
+
+/**
+ * @param {object} options options
+ * @param {string} options.filename filename
+ * @param {OutputFileSystem} options.outputFileSystem output file system
+ * @param {import("range-parser").Range[]} options.ranges ranges
+ * @param {number} options.size size
+ * @param {string | false} options.contentType content type
+ * @returns {{ boundary: string, byteLength: number, bufferOrStream: Readable }} result
+ */
+function createMultipartBody({
+  filename,
+  outputFileSystem,
+  ranges,
+  size,
+  contentType,
+}) {
+  const boundary = crypto.randomBytes(12).toString("hex");
+
+  /** @type {{ start: number, end: number, head: Buffer }[]} */
+  const parts = ranges.map((range) => ({
+    start: range.start,
+    end: range.end,
+    head: Buffer.from(
+      `\r\n--${boundary}\r\n${contentType ? `Content-Type: ${contentType}\r\n` : ""}Content-Range: bytes ${range.start}-${range.end}/${size}\r\n\r\n`,
+    ),
+  }));
+
+  const tail = Buffer.from(`\r\n--${boundary}--\r\n`);
+
+  const byteLength =
+    parts.reduce(
+      (total, part) => total + part.head.length + (part.end - part.start + 1),
+      0,
+    ) + tail.length;
+
+  const isFsSupportsStream =
+    typeof outputFileSystem.createReadStream === "function";
+
+  /** @type {Buffer | undefined} */
+  let cachedFullBuffer;
+  if (!isFsSupportsStream) {
+    cachedFullBuffer = /** @type {Buffer} */ (
+      outputFileSystem.readFileSync(filename)
+    );
+  }
+
+  /**
+   * Each part head, each part body, then the closing boundary.
+   */
+  async function* body() {
+    for (const part of parts) {
+      yield part.head;
+
+      if (isFsSupportsStream) {
+        const { bufferOrStream } = createReadStreamOrReadFile(
+          filename,
+          outputFileSystem,
+          part.start,
+          part.end,
+        );
+
+        if (
+          typeof (
+            /** @type {import("fs").ReadStream} */ (bufferOrStream).pipe
+          ) === "function"
+        ) {
+          try {
+            yield* /** @type {import("fs").ReadStream} */ (bufferOrStream);
+          } finally {
+            destroyStream(
+              /** @type {import("fs").ReadStream} */ (bufferOrStream),
+              true,
+            );
+          }
+        } else {
+          yield /** @type {Buffer} */ (bufferOrStream).subarray(
+            part.start,
+            part.end + 1,
+          );
+        }
+      } else {
+        yield /** @type {Buffer} */ (cachedFullBuffer).subarray(
+          part.start,
+          part.end + 1,
+        );
+      }
+    }
+    yield tail;
+  }
+
+  return {
+    boundary,
+    byteLength,
+    bufferOrStream: Readable.from(body()),
+  };
+}
+
 /**
  * @template {ServerResponse & ExpectedServerResponse} Response
  * @param {Response} res res
@@ -1781,6 +1884,7 @@ module.exports = {
   applyCors,
   clientQuery,
   createMimeTypes,
+  createMultipartBody,
   createReadStreamOrReadFile,
   destroyStream,
   escapeHtml,

test/middleware.test.js

@@ -1294,11 +1294,66 @@ describe.each([
           expect(response.statusCode).toBe(200);
         });
 
-        it('should return the "200" code for the "GET" request with multiple range header which is ignored', async () => {
+        it('should return the "206" code for the "GET" request with multiple range header', async () => {
           const response = await req
             .get("/bundle.js")
             .set("Range", "bytes=3000-3100,3200-3300");
 
+          expect(response.statusCode).toBe(206);
+          expect(response.headers["content-type"]).toMatch(
+            /multipart\/byteranges; boundary=/,
+          );
+          expect(response.headers["content-length"]).toBeDefined();
+        });
+
+        it("should return multipart 206 for two separate ranges", async () => {
+          const response = await req
+            .get("/bundle.js")
+            .set("Range", "bytes=0-9,20-29");
+
+          expect(response.statusCode).toBe(206);
+          expect(response.headers["content-type"]).toMatch(
+            /multipart\/byteranges; boundary=/,
+          );
+          expect(response.headers["content-length"]).toBeDefined();
+        });
+
+        it("should return 206 with multipart Content-Type for HEAD with multiple ranges", async () => {
+          const response = await req
+            .head("/bundle.js")
+            .set("Range", "bytes=0-9,20-29");
+
+          expect(response.statusCode).toBe(206);
+          expect(response.headers["content-type"]).toMatch(
+            /multipart\/byteranges; boundary=/,
+          );
+        });
+
+        it("should return 206 with only valid range when one is satisfiable and one is unsatisfiable", async () => {
+          const response = await req
+            .get("/bundle.js")
+            .set("Range", "bytes=0-9,9999999-");
+
+          expect(response.statusCode).toBe(206);
+        });
+
+        it("should return 416 when all ranges are unsatisfiable", async () => {
+          const response = await req
+            .get("/bundle.js")
+            .set("Range", "bytes=9999999-10000000,19999999-20000000");
+
+          expect(response.statusCode).toBe(416);
+        });
+
+        it("should return 200 when more ranges than cap", async () => {
+          const ranges = [];
+          for (let i = 0; i < 201; i++) {
+            ranges.push(`bytes=${i * 2}-${i * 2 + 1}`);
+          }
+          const response = await req
+            .get("/bundle.js")
+            .set("Range", ranges.join(", "));
+
           expect(response.statusCode).toBe(200);
         });
 

types/utils.d.ts

@@ -163,6 +163,32 @@ export function clientQuery(
 export function createMimeTypes(
   extra?: Record<string, string> | undefined,
 ): MimeTypes;
+/**
+ * @param {object} options options
+ * @param {string} options.filename filename
+ * @param {OutputFileSystem} options.outputFileSystem output file system
+ * @param {import("range-parser").Range[]} options.ranges ranges
+ * @param {number} options.size size
+ * @param {string | false} options.contentType content type
+ * @returns {{ boundary: string, byteLength: number, bufferOrStream: Readable }} result
+ */
+export function createMultipartBody({
+  filename,
+  outputFileSystem,
+  ranges,
+  size,
+  contentType,
+}: {
+  filename: string;
+  outputFileSystem: OutputFileSystem;
+  ranges: import("range-parser").Range[];
+  size: number;
+  contentType: string | false;
+}): {
+  boundary: string;
+  byteLength: number;
+  bufferOrStream: Readable;
+};
 /**
  * @param {string} filename filename
  * @param {OutputFileSystem} outputFileSystem output file system
@@ -583,3 +609,4 @@ export function setState<
 export function setStatusCode<
   Response extends ServerResponse & ExpectedServerResponse,
 >(res: Response, code: number): void;
+import { Readable } from "node:stream";