Refactor session handling

README.md

@@ -226,7 +226,11 @@ Here's what the full _default_ module configuration looks like:
     // Sessions aren't pinned to the user's IP address
     ipPinning: false,
     // Expiration of the sessions are not reset to the original expiryInSeconds on every request
-    rolling: false
+    rolling: false,
+    // Uninitialized, resp. unmodified sessions are saved to the store, so session cookies are set at the first response
+    saveUninitialized: true,
+    // Sessions are saved to the store, even if they were never modified during the request
+    resave: true
   },
   api: {
     // The API is enabled

package.json

@@ -35,6 +35,7 @@
     "argon2": "^0.30.2",
     "dayjs": "^1.11.6",
     "defu": "^6.1.0",
+    "fast-deep-equal": "^3.1.3",
     "h3": "^1.0.1",
     "unstorage": "^1.0.1"
   },

src/module.ts

@@ -26,7 +26,9 @@ const defaults: FilledModuleOptions = {
     },
     domain: false,
     ipPinning: false as boolean|SessionIpPinningOptions,
-    rolling: false
+    rolling: false,
+    saveUninitialized: true,
+    resave: true
   },
   api: {
     isEnabled: true,

src/runtime/server/middleware/session/index.ts

@@ -1,10 +1,12 @@
 import { deleteCookie, eventHandler, H3Event, parseCookies, setCookie } from 'h3'
 import { nanoid } from 'nanoid'
 import dayjs from 'dayjs'
+import equal from 'fast-deep-equal'
 import { SameSiteOptions, Session, SessionOptions } from '../../../../types'
 import { dropStorageSession, getStorageSession, setStorageSession } from './storage'
 import { processSessionIp, getHashedIpAddress } from './ipPinning'
 import { SessionExpired } from './exceptions'
+import { resEndProxy } from './resEndProxy'
 import { useRuntimeConfig } from '#imports'
 
 const SESSION_COOKIE_NAME = 'sessionId'
@@ -66,25 +68,24 @@ export const deleteSession = async (event: H3Event) => {
 }
 
 const newSession = async (event: H3Event) => {
-  const runtimeConfig = useRuntimeConfig()
-  const sessionOptions = runtimeConfig.session.session as SessionOptions
+  const sessionOptions = useRuntimeConfig().session.session as SessionOptions
   const now = new Date()
 
-  // (Re-)Set cookie
-  const sessionId = nanoid(sessionOptions.idLength)
-  safeSetCookie(event, SESSION_COOKIE_NAME, sessionId, now)
-
-  // Store session data in storage
   const session: Session = {
-    id: sessionId,
+    id: nanoid(sessionOptions.idLength),
     createdAt: now,
     ip: sessionOptions.ipPinning ? await getHashedIpAddress(event) : undefined
   }
-  await setStorageSession(sessionId, session)
 
   return session
 }
 
+const setSession = async (session: Session, event: H3Event) => {
+  safeSetCookie(event, SESSION_COOKIE_NAME, session.id, session.createdAt)
+  await setStorageSession(session.id, session)
+  return session
+}
+
 const getSession = async (event: H3Event): Promise<null | Session> => {
   // 1. Does the sessionId cookie exist on the request?
   const existingSessionId = getCurrentSessionId(event)
@@ -98,8 +99,7 @@ const getSession = async (event: H3Event): Promise<null | Session> => {
     return null
   }
 
-  const runtimeConfig = useRuntimeConfig()
-  const sessionOptions = runtimeConfig.session.session as SessionOptions
+  const sessionOptions = useRuntimeConfig().session.session as SessionOptions
   const sessionExpiryInSeconds = sessionOptions.expiryInSeconds
 
   try {
@@ -143,21 +143,31 @@ const ensureSession = async (event: H3Event) => {
 
   event.context.sessionId = session.id
   event.context.session = session
+
   return session
 }
 
 export default eventHandler(async (event: H3Event) => {
+  const sessionOptions = useRuntimeConfig().session.session as SessionOptions
+
   // 1. Ensure that a session is present by either loading or creating one
-  await ensureSession(event)
-
-  // 2. Setup a hook that saves any changed made to the session by the subsequent endpoints & middlewares
-  event.res.on('finish', async () => {
-    // Session id may not exist if session was deleted
-    const session = await getSession(event)
-    if (!session) {
-      return
+  const session = await ensureSession(event)
+  // 2. Save current state of the session
+  const oldSession = { ...session }
+
+  // 3. Setup a hook that saves any changed made to the session by the subsequent endpoints & middlewares
+  resEndProxy(event.node.res, async () => {
+    const newSession = event.context.session as Session
+    const storedSession = await getSession(event)
+
+    if (!storedSession) {
+      // Save a new session if saveUninitialized is true, or if the session has been modified
+      if (sessionOptions.saveUninitialized || !equal(newSession, oldSession)) {
+        await setSession(newSession, event)
+      }
+    // Update the session in the storage if resave is true, or if the stored session has been modified
+    } else if (sessionOptions.resave || !equal(newSession, storedSession)) {
+      await setStorageSession(storedSession.id, newSession)
     }
-
-    await setStorageSession(session.id, event.context.session)
   })
 })

src/runtime/server/middleware/session/resEndProxy.ts

@@ -0,0 +1,14 @@
+import type { ServerResponse } from 'node:http'
+
+type MiddleWare = () => Promise<void>
+
+// Proxy res.end() to get a callback at the end of all event handlers
+export const resEndProxy = (res: ServerResponse, middleWare: MiddleWare) => {
+  const end = res.end
+
+  // @ts-ignore Replacing res.end() will lead to type checking error
+  res.end = async (chunk: any, encoding: BufferEncoding) => {
+    await middleWare()
+    return end.call(res, chunk, encoding) as ServerResponse
+  }
+}

src/types.ts

@@ -104,7 +104,22 @@ export interface SessionOptions {
    * @example true
    * @type boolean
    */
-  rolling: boolean
+  rolling: boolean,
+  /**
+   * Forces a session that is "uninitialized" to be saved to the store. A session is uninitialized when it is new but not modified.
+   * Choosing false is useful for implementing login sessions, reducing server storage usage, or complying with laws that require permission before setting a cookie.
+   * @default true
+   * @example false
+   * @type boolean
+   */
+  saveUninitialized: boolean,
+  /**
+    * Forces the session to be saved back to the session store, even if the session was never modified during the request.
+    * @default true
+    * @example false
+    * @type boolean
+    */
+  resave: boolean
 }
 
 export interface ApiOptions {