feat: support chunked cookies and use for session (#1102)

Co-authored-by: Pooya Parsa <[email protected]>

Author: DavidDeSloovere

docs/2.utils/3.cookie.md

@@ -8,10 +8,18 @@ icon: material-symbols:cookie-outline
 
 <!-- automd:jsdocs src="../../src/utils/cookie.ts" -->
 
+### `deleteChunkedCookie(event, name, serializeOptions?)`
+
+Remove a set of chunked cookies by name.
+
 ### `deleteCookie(event, name, serializeOptions?)`
 
 Remove a cookie by name.
 
+### `getChunkedCookie(event, name)`
+
+Get a chunked cookie value by name. Will join chunks together.
+
 ### `getCookie(event, name)`
 
 Get a cookie value by name.
@@ -20,6 +28,10 @@ Get a cookie value by name.
 
 Parse the request to get HTTP Cookie header string and returning an object of all cookie name-value pairs.
 
+### `setChunkedCookie(event, name, value, options?)`
+
+Set a cookie value by name. Chunked cookies will be created as needed.
+
 ### `setCookie(event, name, value, options?)`
 
 Set a cookie value by name.

src/utils/cookie.ts

@@ -6,6 +6,11 @@ import {
   parseSetCookie,
 } from "cookie-es";
 
+const CHUNKED_COOKIE = "__chunked__";
+
+// The limit is approximately 4KB, but may vary by browser and server. We leave some room to be safe.
+const CHUNKS_MAX_LENGTH = 4000;
+
 /**
  * Parse the request to get HTTP Cookie header string and returning an object of all cookie name-value pairs.
  * @param event {HTTPEvent} H3 event or req passed by h3 handler
@@ -96,6 +101,114 @@ export function deleteCookie(
   });
 }
 
+/**
+ * Get a chunked cookie value by name. Will join chunks together.
+ * @param event {HTTPEvent} { req: Request }
+ * @param name Name of the cookie to get
+ * @returns {*} Value of the cookie (String or undefined)
+ * ```ts
+ * const authorization = getCookie(request, 'Session')
+ * ```
+ */
+export function getChunkedCookie(
+  event: HTTPEvent,
+  name: string,
+): string | undefined {
+  const mainCookie = getCookie(event, name);
+  if (!mainCookie || !mainCookie.startsWith(CHUNKED_COOKIE)) {
+    return mainCookie;
+  }
+
+  const chunksCount = getChunkedCookieCount(mainCookie);
+  if (chunksCount === 0) {
+    return undefined;
+  }
+
+  const chunks = [];
+  for (let i = 1; i <= chunksCount; i++) {
+    const chunk = getCookie(event, chunkCookieName(name, i));
+    if (!chunk) {
+      return undefined;
+    }
+    chunks.push(chunk);
+  }
+
+  return chunks.join("");
+}
+
+/**
+ * Set a cookie value by name. Chunked cookies will be created as needed.
+ * @param event {H3Event} H3 event or res passed by h3 handler
+ * @param name Name of the cookie to set
+ * @param value Value of the cookie to set
+ * @param options {CookieSerializeOptions} Options for serializing the cookie
+ * ```ts
+ * setCookie(res, 'Session', '<session data>')
+ * ```
+ */
+export function setChunkedCookie(
+  event: H3Event,
+  name: string,
+  value: string,
+  options?: CookieSerializeOptions & { chunkMaxLength?: number },
+): void {
+  const chunkMaxLength = options?.chunkMaxLength || CHUNKS_MAX_LENGTH;
+  const chunkCount = Math.ceil(value.length / chunkMaxLength);
+
+  // delete any prior left over chunks if the cookie is updated
+  const previousCookie = getCookie(event, name);
+  if (previousCookie?.startsWith(CHUNKED_COOKIE)) {
+    const previousChunkCount = getChunkedCookieCount(previousCookie);
+    if (previousChunkCount > chunkCount) {
+      for (let i = chunkCount; i <= previousChunkCount; i++) {
+        deleteCookie(event, chunkCookieName(name, i), options);
+      }
+    }
+  }
+
+  if (chunkCount <= 1) {
+    // If the value is small enough, just set it as a normal cookie
+    setCookie(event, name, value, options);
+    return;
+  }
+
+  // If the value is too large, we need to chunk it
+  const mainCookieValue = `${CHUNKED_COOKIE}${chunkCount}`;
+  setCookie(event, name, mainCookieValue, options);
+
+  for (let i = 1; i <= chunkCount; i++) {
+    const start = (i - 1) * chunkMaxLength;
+    const end = start + chunkMaxLength;
+    const chunkValue = value.slice(start, end);
+    setCookie(event, chunkCookieName(name, i), chunkValue, options);
+  }
+}
+
+/**
+ * Remove a set of chunked cookies by name.
+ * @param event {H3Event} H3 event or res passed by h3 handler
+ * @param name Name of the cookie to delete
+ * @param serializeOptions {CookieSerializeOptions} Cookie options
+ * ```ts
+ * deleteCookie(res, 'Session')
+ * ```
+ */
+export function deleteChunkedCookie(
+  event: H3Event,
+  name: string,
+  serializeOptions?: CookieSerializeOptions,
+): void {
+  const mainCookie = getCookie(event, name);
+  deleteCookie(event, name, serializeOptions);
+
+  const chunksCount = getChunkedCookieCount(mainCookie);
+  if (chunksCount >= 0) {
+    for (let i = 0; i < chunksCount; i++) {
+      deleteCookie(event, chunkCookieName(name, i + 1), serializeOptions);
+    }
+  }
+}
+
 /**
  * Cookies are unique by "cookie-name, domain-value, and path-value".
  *
@@ -104,3 +217,14 @@ export function deleteCookie(
 function _getDistinctCookieKey(name: string, options: Partial<SetCookie>) {
   return [name, options.domain || "", options.path || "/"].join(";");
 }
+
+function getChunkedCookieCount(cookie: string | undefined): number {
+  if (!cookie?.startsWith(CHUNKED_COOKIE)) {
+    return Number.NaN;
+  }
+  return Number.parseInt(cookie.slice(CHUNKED_COOKIE.length));
+}
+
+function chunkCookieName(name: string, chunkNumber: number): string {
+  return `${name}.${chunkNumber}`;
+}

src/utils/session.ts

@@ -3,7 +3,7 @@ import {
   unseal,
   defaults as sealDefaults,
 } from "./internal/iron-crypto.ts";
-import { getCookie, setCookie } from "./cookie.ts";
+import { getChunkedCookie, setChunkedCookie } from "./cookie.ts";
 import {
   DEFAULT_SESSION_NAME,
   DEFAULT_SESSION_COOKIE,
@@ -43,7 +43,7 @@ export interface SessionConfig {
   /** default is h3 */
   name?: string;
   /** Default is secure, httpOnly, / */
-  cookie?: false | CookieSerializeOptions;
+  cookie?: false | (CookieSerializeOptions & { chunkMaxLength?: number });
   /** Default is x-h3-session / x-{name}-session */
   sessionHeader?: false | string;
   seal?: SealOptions;
@@ -128,7 +128,7 @@ export async function getSession<T extends SessionData = SessionData>(
   }
   // Fallback to cookies
   if (!sealedSession) {
-    sealedSession = getCookie(event, sessionName);
+    sealedSession = getChunkedCookie(event, sessionName);
   }
   if (sealedSession) {
     // Unseal session data from cookie
@@ -185,7 +185,7 @@ export async function updateSession<T extends SessionData = SessionData>(
   // Seal and store in cookie
   if (config.cookie !== false && (event as H3Event).res) {
     const sealed = await sealSession(event, config);
-    setCookie(event as H3Event, sessionName, sealed, {
+    setChunkedCookie(event as H3Event, sessionName, sealed, {
       ...DEFAULT_SESSION_COOKIE,
       expires: config.maxAge
         ? new Date(session.createdAt + config.maxAge * 1000)
@@ -256,7 +256,7 @@ export function clearSession(
     delete context.sessions![sessionName];
   }
   if ((event as H3Event).res && config.cookie !== false) {
-    setCookie(event as H3Event, sessionName, "", {
+    setChunkedCookie(event as H3Event, sessionName, "", {
       ...DEFAULT_SESSION_COOKIE,
       ...config.cookie,
     });

test/cookies.test.ts

@@ -1,4 +1,10 @@
-import { getCookie, parseCookies, setCookie } from "../src/utils/cookie.ts";
+import {
+  getCookie,
+  parseCookies,
+  setCookie,
+  getChunkedCookie,
+  setChunkedCookie,
+} from "../src/utils/cookie.ts";
 import { describeMatrix } from "./_setup.ts";
 
 describeMatrix("cookies", (t, { it, expect, describe }) => {
@@ -106,4 +112,99 @@ describeMatrix("cookies", (t, { it, expect, describe }) => {
     ]);
     expect(await result.text()).toBe("200");
   });
+
+  describeMatrix("chunked", (t, { it, expect, describe }) => {
+    const CHUNKED_COOKIE = "__chunked__";
+
+    describe("getChunkedCookie", () => {
+      it("can parse cookie that is chunked", async () => {
+        t.app.get("/", (event) => {
+          const authorization = getChunkedCookie(event, "Authorization");
+          expect(authorization).toEqual("123456789");
+          return "200";
+        });
+
+        const result = await t.fetch("/", {
+          headers: {
+            Cookie: [
+              `Authorization=${CHUNKED_COOKIE}3`,
+              "Authorization.1=123",
+              "Authorization.2=456",
+              "Authorization.3=789",
+            ].join("; "),
+          },
+        });
+
+        expect(await result.text()).toBe("200");
+      });
+
+      it("can parse cookie that is not chunked", async () => {
+        t.app.get("/", (event) => {
+          const authorization = getChunkedCookie(event, "Authorization");
+          expect(authorization).toEqual("not-chunked");
+          return "200";
+        });
+
+        const result = await t.fetch("/", {
+          headers: {
+            Cookie: ["Authorization=not-chunked"].join("; "),
+          },
+        });
+
+        expect(await result.text()).toBe("200");
+      });
+    });
+
+    describe("setChunkedCookie", () => {
+      it("can set-cookie with setChunkedCookie", async () => {
+        t.app.get("/", (event) => {
+          setChunkedCookie(event, "Authorization", "1234567890ABCDEFGHIJXYZ", {
+            chunkMaxLength: 10,
+          });
+          return "200";
+        });
+        const result = await t.fetch("/");
+        expect(result.headers.getSetCookie()).toMatchInlineSnapshot(`
+          [
+            "Authorization=__chunked__3; Path=/",
+            "Authorization.1=1234567890; Path=/",
+            "Authorization.2=ABCDEFGHIJ; Path=/",
+            "Authorization.3=XYZ; Path=/",
+          ]
+        `);
+        expect(await result.text()).toBe("200");
+      });
+
+      it("smaller set-cookie removes superfluous chunks", async () => {
+        // set smaller cookie with fewer chunks, should have deleted superfluous chunks
+        t.app.get("/", (event) => {
+          setChunkedCookie(event, "Authorization", "0000100002", {
+            chunkMaxLength: 5,
+          });
+          return "200";
+        });
+        const result = await t.fetch("/", {
+          headers: {
+            Cookie: [
+              `Authorization=${CHUNKED_COOKIE}4; Path=/`,
+              "Authorization.1=00001; Path=/",
+              "Authorization.2=00002; Path=/",
+              "Authorization.3=00003; Path=/",
+              "Authorization.4=00004; Path=/",
+            ].join("; "),
+          },
+        });
+        expect(result.headers.getSetCookie()).toMatchInlineSnapshot(`
+          [
+            "Authorization.3=; Max-Age=0; Path=/",
+            "Authorization.4=; Max-Age=0; Path=/",
+            "Authorization=__chunked__2; Path=/",
+            "Authorization.1=00001; Path=/",
+            "Authorization.2=00002; Path=/",
+          ]
+        `);
+        expect(await result.text()).toBe("200");
+      });
+    });
+  });
 });

test/session.test.ts

@@ -81,4 +81,23 @@ describeMatrix("session", (t, { it, expect }) => {
       sessions: [1, 2, 3].map(() => ({ id: "1", data: { foo: "bar" } })),
     });
   });
+
+  it("stores large data in chunks", async () => {
+    const token = Array.from({ length: 5000 /* ~4k + one more */ })
+      .fill("x")
+      .join("");
+    const res = await t.fetch("/", {
+      method: "POST",
+      headers: { Cookie: cookie },
+      body: JSON.stringify({ token }),
+    });
+
+    const cookies = res.headers.getSetCookie();
+    const cookieNames = cookies.map((c) => c.split("=")[0]);
+    expect(cookieNames.length).toBe(3 /* head + 2 */);
+    expect(cookieNames).toMatchObject(["h3-test", "h3-test.1", "h3-test.2"]);
+
+    const body = await res.json();
+    expect(body.session.data.token).toBe(token);
+  });
 });