feat: implement modifyHeaders function (#179)

packages/base/headers/readme.md

@@ -1,6 +1,32 @@
 # `@hattip/headers`
 
-Header parsing and content negotiation utilities for Hattip.
+Header manipulation, parsing, and content negotiation utilities for Hattip.
+
+## `modifyHeaders`
+
+Some `Response` objects have an immutable `headers` property. `Response.redirect()`, for instance, creates such an object. When the headers are immutable, a naive middleware to modify the headers will fail:
+
+```js
+async function naivePoweredBy(ctx) {
+  const response = await ctx.next();
+  // The following line will throw an error if `response.headers` is immutable
+  response.headers.set("X-Powered-By", "Hattip");
+  return response;
+}
+```
+
+The `modifyHeaders` function solves this problem by trying to modify the headers in place, and if that fails, creating a new `Response` object and trying again:
+
+```js
+async function correctPoweredBy(ctx) {
+  let response = await ctx.next();
+  response = modifyHeaders(response, (headers) => {
+    headers.set("X-Powered-By", "Hattip");
+  });
+
+  return response;
+}
+```
 
 ## `parseHeaderValue`
 

packages/base/headers/src/index.ts

@@ -4,3 +4,5 @@ export type { ParsedHeaderValue } from "./parser";
 export { accept } from "./accept";
 
 export { acceptLanguage } from "./accept-language";
+
+export { modifyHeaders } from "./modify-headers";

packages/base/headers/src/modify-headers.test.ts

@@ -0,0 +1,28 @@
+import { it, expect } from "vitest";
+import { modifyHeaders } from "./modify-headers";
+
+it("modifies mutable headers", () => {
+	const response = new Response("body", {
+		headers: { "Some-Header": "value" },
+	});
+
+	const modified = modifyHeaders(response, (headers) => {
+		headers.set("Some-Header", "modified");
+		headers.set("New-Header", "new");
+	});
+
+	expect(modified).toBe(response); // Should be in-place
+	expect(modified.headers.get("Some-Header")).toBe("modified");
+	expect(modified.headers.get("New-Header")).toBe("new");
+});
+
+it("modifies immutable headers", () => {
+	const response = Response.redirect("http://example.com");
+
+	const modified = modifyHeaders(response, (headers) => {
+		headers.set("Some-Header", "modified");
+	});
+
+	expect(modified).not.toBe(response); // Should not be in-place
+	expect(modified.headers.get("Some-Header")).toBe("modified");
+});

packages/base/headers/src/modify-headers.ts

@@ -0,0 +1,43 @@
+/**
+ * Tries to modify the headers of a response, and, if it fails,
+ * creates a mutable copy of the response and tries again.
+ *
+ * The problem that this function solves is that some responses
+ * have immutable headers and there is no way to know this without
+ * trying to modify them. This function solves this problem by
+ * trying to modify the headers and, if it fails, creating a copy
+ * of the response with the same body and headers and trying again.
+ *
+ * Usage:
+ *
+ * ```ts
+ * app.use(async (ctx) => {
+ *   let response = await ctx.next();
+ *   response = modifyHeaders(response, (headers) => {
+ *     headers.set("X-Powered-By", "Hattip");
+ *   });
+ *
+ *   return response;
+ * });
+ * ```
+ *
+ * @param response Response object to be modified
+ * @param modify Callback to modify the headers
+ *
+ * @returns a Response object with modified headers. It will be
+ * the same object as the argument if its headers are mutable,
+ * otherwise it will be a copy of the original.
+ */
+export function modifyHeaders(
+	response: Response,
+	modify: (headers: Headers) => void,
+): Response {
+	try {
+		modify(response.headers);
+		return response;
+	} catch {
+		const clone = new Response(response.body, response);
+		modify(clone.headers);
+		return clone;
+	}
+}

packages/middleware/cookie/package.json

@@ -33,6 +33,7 @@
   "dependencies": {
     "@hattip/compose": "workspace:*",
     "@hattip/core": "workspace:*",
+    "@hattip/headers": "workspace:*",
     "cookie": "^1.0.1"
   },
   "devDependencies": {

packages/middleware/cookie/src/serialize.ts

@@ -1,5 +1,6 @@
 import "@hattip/compose";
 import type { RequestContext } from "@hattip/compose";
+import { modifyHeaders } from "@hattip/headers";
 import { serialize, SerializeOptions as CookieSerializeOptions } from "cookie";
 
 declare module "@hattip/compose" {
@@ -74,10 +75,12 @@ export function cookieSerializer(defaultOptions?: CookieSerializeOptions) {
 			});
 		};
 
-		const response: Response = await ctx.next();
+		let response: Response = await ctx.next();
 
 		for (const { name, value, options } of ctx.outgoingCookies) {
-			response.headers.append("set-cookie", serialize(name, value, options));
+			response = modifyHeaders(response, (headers) => {
+				headers.append("set-cookie", serialize(name, value, options));
+			});
 		}
 
 		return response;

packages/middleware/cors/package.json

@@ -31,6 +31,7 @@
   "dependencies": {
     "@hattip/compose": "workspace:*",
     "@hattip/core": "workspace:*",
+    "@hattip/headers": "workspace:*",
     "@types/cookie": "^1.0.0",
     "cookie": "^1.0.1"
   },

packages/middleware/cors/src/index.ts

@@ -1,4 +1,5 @@
 import { RequestContext } from "@hattip/compose";
+import { modifyHeaders } from "@hattip/headers";
 
 /** CORS middleware */
 export function cors(options: CorsOptions = {}) {
@@ -30,8 +31,11 @@ export function cors(options: CorsOptions = {}) {
 		const requestOrigin = ctx.request.headers.get("Origin");
 
 		if (!requestOrigin) {
-			const response = await ctx.next();
-			response.headers.append("Vary", "Origin");
+			let response = await ctx.next();
+			response = modifyHeaders(response, (headers) => {
+				headers.append("Vary", "Origin");
+			});
+
 			return response;
 		}
 
@@ -51,12 +55,16 @@ export function cors(options: CorsOptions = {}) {
 			credentials = !!options.credentials;
 		}
 
-		const response =
+		let response =
 			ctx.method === "OPTIONS"
 				? new Response(null, { status: 204 })
 				: await ctx.next();
 
-		response.headers.append("Vary", "Origin");
+		response = modifyHeaders(response, (headers) => {
+			headers.append("Vary", "Origin");
+		});
+
+		// From here on we can assume that the response has a mutable headers object
 
 		const headersSet: Record<string, string | string[]> = {};