@c9up/ream 0.2.27 → 0.2.28

package/src/session/drivers/FileDriver.ts

@@ -16,6 +16,18 @@ export interface FileDriverOptions {
   location: string
 }
 
+/** How long a writer waits for a session's lock before giving up. */
+const LOCK_WAIT_MS = 2000
+/**
+ * A lock older than this was left by a process that died holding it. Every
+ * operation under the lock is one small file read or write, far below it.
+ */
+const LOCK_STALE_MS = 10_000
+
+function hasCode(error: unknown, code: string): boolean {
+  return error instanceof Error && Reflect.get(error, 'code') === code
+}
+
 export class FileDriver implements SessionDriver {
   readonly #location: string
 
@@ -37,6 +49,17 @@ export class FileDriver implements SessionDriver {
   }
 
   async read(sessionId: string): Promise<Record<string, unknown> | null> {
+    return this.#read(sessionId, () => this.destroy(sessionId))
+  }
+
+  /**
+   * Read, dropping an expired file through `drop`: `destroy()` from outside,
+   * a bare removal from inside the lock, which is already held there.
+   */
+  async #read(
+    sessionId: string,
+    drop: () => Promise<void>,
+  ): Promise<Record<string, unknown> | null> {
     let raw: string
     try {
       raw = await fs.promises.readFile(this.#pathFor(sessionId), 'utf8')
@@ -48,7 +71,7 @@ export class FileDriver implements SessionDriver {
       if (typeof parsed !== 'object' || parsed === null) return null
       const entry = parsed as { expiresAt?: number; data?: Record<string, unknown> }
       if (typeof entry.expiresAt === 'number' && entry.expiresAt < Date.now()) {
-        await this.destroy(sessionId)
+        await drop()
         return null
       }
       return entry.data ?? {}
@@ -60,6 +83,43 @@ export class FileDriver implements SessionDriver {
   }
 
   async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
+    await this.#locked(sessionId, () => this.#replace(sessionId, data, ttl))
+  }
+
+  /**
+   * Written only while the file is still there. A filesystem has no
+   * conditional write, so every change to a session's file — this, `write`,
+   * `destroy` and `touch` — runs under that session's lock: a `destroy` from a
+   * logout cannot land between the check and the write, in this process or in
+   * another one sharing the directory.
+   */
+  async update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean> {
+    return this.#locked(sessionId, async () => {
+      if ((await this.#read(sessionId, () => this.#remove(sessionId))) === null) return false
+      await this.#replace(sessionId, data, ttl)
+      return true
+    })
+  }
+
+  async destroy(sessionId: string): Promise<void> {
+    await this.#locked(sessionId, () => this.#remove(sessionId))
+  }
+
+  async #remove(sessionId: string): Promise<void> {
+    await fs.promises.rm(this.#pathFor(sessionId), { force: true })
+  }
+
+  async touch(sessionId: string, ttl: number): Promise<void> {
+    await this.#locked(sessionId, async () => {
+      const data = await this.#read(sessionId, () => this.#remove(sessionId))
+      // Nothing stored: there is no expiry to slide, and writing here would
+      // create the very session that was not there.
+      if (data === null || Object.keys(data).length === 0) return
+      await this.#replace(sessionId, data, ttl)
+    })
+  }
+
+  async #replace(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
     const file = this.#pathFor(sessionId)
     const payload = JSON.stringify({ expiresAt: Date.now() + ttl * 1000, data })
     // Written to a temporary neighbour then renamed: a crash mid-write would
@@ -70,15 +130,35 @@ export class FileDriver implements SessionDriver {
     await fs.promises.rename(temp, file)
   }
 
-  async destroy(sessionId: string): Promise<void> {
-    await fs.promises.rm(this.#pathFor(sessionId), { force: true })
-  }
-
-  async touch(sessionId: string, ttl: number): Promise<void> {
-    const data = await this.read(sessionId)
-    // Nothing stored: there is no expiry to slide, and writing here would
-    // create the very session that was not there.
-    if (data === null || Object.keys(data).length === 0) return
-    await this.write(sessionId, data, ttl)
+  /**
+   * Run `fn` holding the session's lock: a directory beside its file, which
+   * `mkdir` creates atomically or refuses — the one exclusive primitive every
+   * filesystem gives, across processes too.
+   */
+  async #locked<T>(sessionId: string, fn: () => Promise<T>): Promise<T> {
+    const lock = `${this.#pathFor(sessionId)}.lock`
+    const deadline = Date.now() + LOCK_WAIT_MS
+    for (;;) {
+      try {
+        await fs.promises.mkdir(lock)
+        break
+      } catch (error) {
+        if (!hasCode(error, 'EEXIST')) throw error
+        const held = await fs.promises.stat(lock).catch(() => null)
+        if (held !== null && Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+          await fs.promises.rm(lock, { recursive: true, force: true })
+          continue
+        }
+        if (Date.now() > deadline) {
+          throw new Error(`Session file is locked: ${lock}`)
+        }
+        await new Promise((resolve) => setTimeout(resolve, 5))
+      }
+    }
+    try {
+      return await fn()
+    } finally {
+      await fs.promises.rmdir(lock).catch(() => {})
+    }
   }
 }

package/src/session/drivers/MemoryDriver.ts

@@ -57,6 +57,15 @@ export class MemoryDriver implements SessionDriverWithTagging {
     }
   }
 
+  /** Atomic by construction: nothing else runs between the check and the set. */
+  async update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean> {
+    const entry = this.#store.get(sessionId)
+    if (!entry || entry.expiresAt < Date.now()) return false
+    this.#store.delete(sessionId)
+    this.#store.set(sessionId, { data, expiresAt: Date.now() + ttl * 1000 })
+    return true
+  }
+
   async destroy(sessionId: string): Promise<void> {
     this.#store.delete(sessionId)
     // Drop the tags too: a destroyed session left in the index would be

package/src/session/drivers/RedisDriver.ts

@@ -142,6 +142,13 @@ export class RedisDriver implements SessionDriverWithTagging {
     await client.set(this.#key(sessionId), JSON.stringify(data), 'EX', ttl)
   }
 
+  /** `XX` makes the existence check and the write one command. */
+  async update(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<boolean> {
+    const client = await this.#client()
+    const reply = await client.set(this.#key(sessionId), JSON.stringify(data), 'EX', ttl, 'XX')
+    return reply !== null
+  }
+
   async destroy(sessionId: string): Promise<void> {
     const client = await this.#client()
     await client.del(this.#key(sessionId))

package/src/session/errors.ts

@@ -25,6 +25,23 @@ export class E_SESSION_NOT_READY extends Exception {
   }
 }
 
+/**
+ * A store with no `update()`: it cannot write a session back only while its
+ * entry still exists, so a request running across a logout could sign the
+ * user in again. Refused when the store is attached, not at the first race.
+ */
+export class E_SESSION_STORE_NOT_CONDITIONAL extends Exception {
+  static override status = 500
+  static override code = 'E_SESSION_STORE_NOT_CONDITIONAL'
+
+  constructor() {
+    super(
+      'This session store has no update(): it must write a session only over an entry that still exists, in one step. See "Writing a session store".',
+      { status: 500, code: 'E_SESSION_STORE_NOT_CONDITIONAL' },
+    )
+  }
+}
+
 /** The configured store cannot tag sessions (cookie and file stores cannot). */
 export class E_SESSION_TAGGING_NOT_SUPPORTED extends Exception {
   static override status = 500