feat: Implement 'no-cors' mode for fetch (#62)

Author: nzakas

src/cors.js

@@ -78,6 +78,13 @@ const simpleRequestContentTypes = new Set([
 	"text/plain",
 ]);
 
+const noCorsSafeHeaders = new Set([
+	"accept",
+	"accept-language",
+	"content-language",
+	"content-type",
+]);	
+
 // the methods that are forbidden to be used with CORS
 export const forbiddenMethods = new Set(["CONNECT", "TRACE", "TRACK"]);
 
@@ -168,6 +175,74 @@ function isSimpleRangeHeader(range) {
 	return firstIsNumber && secondIsNumber;
 }
 
+/**
+ * Checks if a string contains any CORS-unsafe request-header bytes.
+ * @param {string} str The string to check.
+ * @returns {boolean} `true` if the string contains CORS-unsafe bytes, `false` otherwise.
+ * @see https://fetch.spec.whatwg.org/#cors-unsafe-request-header-byte
+ */
+function containsCorsUnsafeRequestHeaderByte(str) {
+	
+	// eslint-disable-next-line no-control-regex
+	const unsafeBytePattern = /[\x00-\x08\x0A-\x1F\x22\x28\x29\x3A\x3C\x3E\x3F\x40\x5B\x5C\x5D\x7B\x7D\x7F]/u;
+	return unsafeBytePattern.test(str);
+}
+
+/**
+ * Checks if a request header is safe to be used with "no-cors" mode.
+ * @param {string} name The name of the header.
+ * @param {string} value The value of the header.
+ * @returns {boolean} `true` if the header is safe, `false` otherwise.
+ * @see https://fetch.spec.whatwg.org/#no-cors-safelisted-request-header-name
+ */
+function isNoCorsSafeListedRequestHeader(name, value) {
+	
+	if (!noCorsSafeHeaders.has(name.toLowerCase())) {
+		return false;
+	}
+	
+	return isCorsSafeListedRequestHeader(name, value);
+}
+
+/**
+ * Checks if a request header is safe to be used with CORS.
+ * @param {string} name The name of the header.
+ * @param {string} value The value of the header.
+ * @returns {boolean} `true` if the header is safe, `false` otherwise.
+ * @see https://fetch.spec.whatwg.org/#cors-safelisted-request-header
+ */
+function isCorsSafeListedRequestHeader(name, value) {
+	
+	if (value.length > 128) {
+		return false;
+	}
+	
+	const hasUnsafeByte = containsCorsUnsafeRequestHeaderByte(value);
+	
+	switch (name.toLowerCase()) {
+		case "accept":
+			return !hasUnsafeByte;
+			
+		case "accept-language":
+		case "content-language":
+			return !/[^0-9A-Za-z *,\-.=;]/.test(value);
+			
+		case "content-type":
+			if (hasUnsafeByte) {
+				return false;
+			}
+			
+			return simpleRequestContentTypes.has(value.toLowerCase());
+			
+		case "range":
+			return isSimpleRangeHeader(value);
+			
+		default:
+			return false;
+	}
+	
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
@@ -304,6 +379,40 @@ export function assertCorsCredentials(response, origin) {
 	}
 }
 
+/**
+ * Asserts that a request is valid for "no-cors" mode.
+ * @param {RequestInit} requestInit The request to check.
+ * @returns {void}
+ * @throws {TypeError} When the request is not valid for "no-cors" mode.
+ */
+export function assertValidNoCorsRequestInit(requestInit = {}) {
+	const headers = requestInit.headers;
+	const method = requestInit.method;
+	
+	// no method means GET
+	if (!method && !headers) {
+		return;
+	}
+	
+	// otherwise check it
+	if (method && !safeMethods.has(method)) {
+		throw new TypeError(`Method '${method}' is not allowed in 'no-cors' mode.`);
+	}
+	
+	// no headers means nothing to check
+	if (!headers) {
+		return;
+	}
+	
+	const headerKeyValues = Array.from(headers instanceof Headers ? headers.entries() : Object.entries(headers));
+
+	for (const [header, value] of headerKeyValues) {
+		if (!isNoCorsSafeListedRequestHeader(header, value)) {
+			throw new TypeError(`Header '${header}' is not allowed in 'no-cors' mode.`);
+		}
+	}
+}	
+
 /**
  * Processes a CORS response to ensure it's valid and doesn't contain
  * any forbidden headers.

src/custom-request.js

@@ -3,6 +3,11 @@
  * @author Nicholas C. Zakas
  */
 
+//-----------------------------------------------------------------------------
+// Imports
+//-----------------------------------------------------------------------------
+
+import { assertValidNoCorsRequestInit } from "./cors.js";
 
 //-----------------------------------------------------------------------------
 // Exports
@@ -29,6 +34,16 @@ export function createCustomRequest(RequestClass) {
          * @param {RequestInit} [init] The options for the fetch.
          */
         constructor(input, init) {
+
+            /*
+             * Not all runtimes validate the `mode` property correctly.
+             * To ensure consistency across runtimes, we do the validation
+             * and throw a consistent error.
+             */
+            if (init?.mode === "no-cors") {
+                assertValidNoCorsRequestInit(init);
+            }
+            
             super(input, init);
 
             // ensure id is not writable

src/fetch-mocker.js

@@ -105,6 +105,32 @@ function isSameOrigin(requestUrl, baseUrl) {
 	return requestUrl.origin === baseUrl.origin;
 }
 
+/**
+ * Creates an opaque response.
+ * @param {typeof Response} ResponseConstructor The Response constructor to use
+ * @returns {Response} An opaque response
+ */
+function createOpaqueResponse(ResponseConstructor) {
+	const response = new ResponseConstructor(null, {
+		status: 200, // doesn't accept a 0 status
+		statusText: "",
+		headers: {},
+	});
+
+	// Define non-configurable properties to match opaque response behavior
+	Object.defineProperties(response, {
+		type: { value: "opaque", configurable: false },
+		url: { value: "", configurable: false },
+		ok: { value: false, configurable: false },
+		redirected: { value: false, configurable: false },
+		body: { value: null, configurable: false },
+		bodyUsed: { value: false, configurable: false },
+		status: { value: 0, configurable: false },
+	});
+
+	return response;
+}
+
 //-----------------------------------------------------------------------------
 // Exports
 //-----------------------------------------------------------------------------
@@ -216,6 +242,7 @@ export class FetchMocker {
 			let useCors = false;
 			let useCorsCredentials = false;
 			let preflightData;
+			let isSimpleRequest = false;
 
 			// if there's a base URL then we need to check for CORS
 			if (this.#baseUrl) {
@@ -228,12 +255,13 @@ export class FetchMocker {
 					}
 				} else {
 					useCors = true;
+					isSimpleRequest = isCorsSimpleRequest(request);
 					const includeCredentials =
 						request.credentials === "include";
 
 					validateCorsRequest(request, this.#baseUrl.origin);
 
-					if (isCorsSimpleRequest(request)) {
+					if (isSimpleRequest) {
 						if (includeCredentials) {
 							useCorsCredentials = true;
 							this.#attachCredentialsToRequest(request);
@@ -268,6 +296,12 @@ export class FetchMocker {
 			const response = await this.#internalFetch(request, init?.body);
 
 			if (useCors && this.#baseUrl) {
+				
+				// handle no-cors mode for any cross-origin request
+				if (isSimpleRequest && request.mode === "no-cors") {
+					return createOpaqueResponse(this.#Response);
+				}
+				
 				processCorsResponse(
 					response,
 					this.#baseUrl.origin,
@@ -310,6 +344,7 @@ export class FetchMocker {
 	 * @throws {Error} When no route is matched.
 	 */
 	async #internalFetch(request, body = null) {
+
 		const allTraces = [];
 
 		/*

tests/custom-request.test.js

@@ -52,12 +52,29 @@ describe("createCustomRequest()", () => {
         assert.ok(request instanceof Request);
     });
 
-    it("should have a default mode of 'cors'", () => {
-        const request = new CustomRequest(TEST_URL);
+    describe("mode", () => {
+
+        it("should have a default mode of 'cors'", () => {
+            const request = new CustomRequest(TEST_URL);
+            
+            assert.strictEqual(request.mode, "cors");
+        });
+        
+        it("should throw an error when 'no-cors' mode is used with PUT method", () => {
+            assert.throws(() => {
+                new CustomRequest(TEST_URL, { method: "PUT", mode: "no-cors" });
+            }, /Method 'PUT' is not allowed in 'no-cors' mode/);
+        });
+        
+        it("should throw an error when 'no-cors' mode is used with a custom header", () => {
+            assert.throws(() => {
+                new CustomRequest(TEST_URL, { headers: { "X-Custom-Header": "value" }, mode: "no-cors" });
+            }, /Header 'X-Custom-Header' is not allowed in 'no-cors' mode/);
+        });
 
-        assert.strictEqual(request.mode, "cors");
     });
 
+    
     describe("clone()", () => {
 
         it("should have the same class as the original request", () => {

tests/fetch-mocker.test.js

@@ -2416,4 +2416,84 @@ describe("FetchMocker", () => {
 			assert.strictEqual(testObject.customFetch, originalCustomFetch);
 		});
 	});
+
+	describe("no-cors mode", () => {
+		it("should return an opaque response when mode is no-cors", async () => {
+			const server = new MockServer(API_URL);
+			const fetchMocker = new FetchMocker({
+				servers: [server],
+				baseUrl: ALT_BASE_URL,
+			});
+
+			server.get("/hello", {
+				status: 200,
+				body: "Hello world!",
+			});
+
+			const response = await fetchMocker.fetch(API_URL + "/hello", {
+				mode: "no-cors"
+			});
+
+			assert.strictEqual(response.type, "opaque");
+			assert.strictEqual(response.url, "");
+			assert.strictEqual(response.status, 0);
+			assert.strictEqual(response.statusText, "");
+			assert.strictEqual(response.ok, false);
+			assert.strictEqual(response.redirected, false);
+			assert.strictEqual(response.body, null);
+			assert.strictEqual(response.bodyUsed, false);
+			assert.deepStrictEqual([...response.headers.entries()], []);
+		});
+
+		it("should throw when using no-cors mode with non-simple request", async () => {
+			const server = new MockServer(API_URL);
+			const fetchMocker = new FetchMocker({
+				servers: [server],
+				baseUrl: ALT_BASE_URL,
+			});
+
+			server.put("/hello", {
+				status: 200,
+				body: "Hello world!",
+			});
+
+			await assert.rejects(
+				fetchMocker.fetch(API_URL + "/hello", {
+					mode: "no-cors",
+					method: "PUT"
+				}),
+				{
+					name: "TypeError",
+					message: "Method 'PUT' is not allowed in 'no-cors' mode."
+				}
+			);
+		});
+
+		it("should return an opaque response regardless of actual server response", async () => {
+			const server = new MockServer(API_URL);
+			const fetchMocker = new FetchMocker({
+				servers: [server],
+				baseUrl: ALT_BASE_URL,
+			});
+
+			server.get("/hello", {
+				status: 404,
+				statusText: "Not Found",
+				headers: {
+					"X-Custom": "value"
+				},
+				body: "Not found!"
+			});
+
+			const response = await fetchMocker.fetch(API_URL + "/hello", {
+				mode: "no-cors"
+			});
+
+			assert.strictEqual(response.type, "opaque");
+			assert.strictEqual(response.status, 0);
+			assert.strictEqual(response.statusText, "");
+			assert.deepStrictEqual([...response.headers.entries()], []);
+			assert.strictEqual(response.body, null);
+		});
+	});
 });