@c9up/ream 0.1.32 → 0.1.33

package/src/session/drivers/DatabaseDriver.ts

@@ -0,0 +1,184 @@
+import type { SessionDriverWithTagging, TaggedSession } from '../Session.js'
+
+/**
+ * The little a session store needs of a database connection.
+ *
+ * Structural on purpose: ream must not import atlas to store a session, so any
+ * connection exposing these two methods works — atlas, a test double, or an
+ * app's own wrapper.
+ */
+export interface SessionDbConnection {
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
+  execute(sql: string, params?: unknown[]): Promise<{ rowsAffected: number }>
+}
+
+export interface DatabaseDriverOptions {
+  connection: SessionDbConnection
+  /** Table holding the sessions. Default `sessions`. */
+  tableName?: string
+  /**
+   * Percent chance that a write also sweeps expired rows (AdonisJS
+   * `gcProbability`, default 2).
+   *
+   * Without it nothing collects them: `read()` only drops a row it happens to
+   * look at, so a session whose owner never comes back stays in the table
+   * forever. `0` turns the sweep off, for a deployment that prunes on a
+   * schedule instead — see {@link DatabaseDriver.prune}.
+   */
+  gcProbability?: number
+}
+
+/** AdonisJS's default: two writes in a hundred pay for the cleanup. */
+const DEFAULT_GC_PROBABILITY = 2
+
+/**
+ * Database-backed sessions (AdonisJS `database` store).
+ *
+ * The fit is several app instances sharing one database and no Redis: every
+ * instance reads the same sessions, which neither the memory nor the file store
+ * can do.
+ *
+ * The table it expects:
+ *
+ *   id          varchar primary key
+ *   data        text
+ *   expires_at  bigint     -- epoch ms
+ *   user_id     varchar null  -- session tagging; nullable, only set at login
+ */
+export class DatabaseDriver implements SessionDriverWithTagging {
+  readonly #db: SessionDbConnection
+  readonly #table: string
+  readonly #gcProbability: number
+
+  constructor(options: DatabaseDriverOptions) {
+    this.#db = options.connection
+    const gc = options.gcProbability ?? DEFAULT_GC_PROBABILITY
+    if (!Number.isFinite(gc) || gc < 0 || gc > 100) {
+      throw new Error(
+        `Session gcProbability must be a percentage between 0 and 100, got ${String(options.gcProbability)}.`,
+      )
+    }
+    this.#gcProbability = gc
+    const table = options.tableName ?? 'sessions'
+    // The table name is concatenated into the SQL (it cannot be a bind
+    // parameter), so it is restricted to an identifier rather than trusted.
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) {
+      throw new Error(
+        `Session table name "${table}" is not a plain identifier — letters, digits and underscores only.`,
+      )
+    }
+    this.#table = table
+  }
+
+  async read(sessionId: string): Promise<Record<string, unknown>> {
+    const rows = await this.#db.query<{ data: string; expires_at: number | string }>(
+      `SELECT data, expires_at FROM ${this.#table} WHERE id = ?`,
+      [sessionId],
+    )
+    const row = rows[0]
+    if (!row) return {}
+    if (Number(row.expires_at) < Date.now()) {
+      await this.destroy(sessionId)
+      return {}
+    }
+    return parseData(row.data)
+  }
+
+  async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
+    const payload = JSON.stringify(data)
+    const expiresAt = Date.now() + ttl * 1000
+    // UPDATE-then-INSERT rather than a dialect-specific upsert: `ON CONFLICT`
+    // and `ON DUPLICATE KEY` are spelled differently by each engine, and this
+    // store has to work on all of them.
+    const updated = await this.#db.execute(
+      `UPDATE ${this.#table} SET data = ?, expires_at = ? WHERE id = ?`,
+      [payload, expiresAt, sessionId],
+    )
+    if (updated.rowsAffected > 0) {
+      await this.#collectGarbage()
+      return
+    }
+    await this.#db.execute(`INSERT INTO ${this.#table} (id, data, expires_at) VALUES (?, ?, ?)`, [
+      sessionId,
+      payload,
+      expiresAt,
+    ])
+    await this.#collectGarbage()
+  }
+
+  /**
+   * Sweep expired rows on a fraction of writes (AdonisJS `#collectGarbage`).
+   *
+   * Best-effort: a failed sweep must not fail the request that happened to draw
+   * the short straw. What it did not remove, the next write that does will.
+   */
+  async #collectGarbage(): Promise<void> {
+    if (this.#gcProbability <= 0) return
+    if (Math.random() * 100 >= this.#gcProbability) return
+    try {
+      await this.prune()
+    } catch {
+      // See above — the session was written, which is what the request needed.
+    }
+  }
+
+  async destroy(sessionId: string): Promise<void> {
+    await this.#db.execute(`DELETE FROM ${this.#table} WHERE id = ?`, [sessionId])
+  }
+
+  async touch(sessionId: string, ttl: number): Promise<void> {
+    await this.#db.execute(`UPDATE ${this.#table} SET expires_at = ? WHERE id = ?`, [
+      Date.now() + ttl * 1000,
+      sessionId,
+    ])
+  }
+
+  /**
+   * Associate the session with a user (AdonisJS's database store does the same:
+   * a nullable `user_id` column, set at login).
+   */
+  async tag(sessionId: string, userId: string | number): Promise<void> {
+    await this.#db.execute(`UPDATE ${this.#table} SET user_id = ? WHERE id = ?`, [
+      String(userId),
+      sessionId,
+    ])
+  }
+
+  /**
+   * Drop the association. Scoped to the user id as well as the session, so a
+   * logout cannot clear a tag another user's session happens to hold.
+   */
+  async untag(sessionId: string, userId: string | number): Promise<void> {
+    await this.#db.execute(
+      `UPDATE ${this.#table} SET user_id = NULL WHERE id = ? AND user_id = ?`,
+      [sessionId, String(userId)],
+    )
+  }
+
+  /** Every non-expired session this user holds — their active devices. */
+  async tagged(userId: string | number): Promise<TaggedSession[]> {
+    const rows = await this.#db.query<{ id: string; data: string }>(
+      `SELECT id, data FROM ${this.#table} WHERE user_id = ? AND expires_at >= ?`,
+      [String(userId), Date.now()],
+    )
+    return rows.map((row) => ({ id: row.id, data: parseData(row.data) }))
+  }
+
+  /** Delete every expired row — for a scheduled job, since nothing else does. */
+  async prune(): Promise<void> {
+    await this.#db.execute(`DELETE FROM ${this.#table} WHERE expires_at < ?`, [Date.now()])
+  }
+}
+
+/**
+ * A stored payload back into an object. An unreadable row is an absent session
+ * rather than a half-parsed object handed to the app.
+ */
+function parseData(raw: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : {}
+  } catch {
+    return {}
+  }
+}

package/src/session/drivers/FileDriver.ts

@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { SessionDriver } from '../Session.js'
+
+/**
+ * File-backed sessions (AdonisJS `file` store) — one file per session id.
+ *
+ * The fit is a single machine that must survive a restart without running a
+ * Redis: the data outlives the process, which the memory store cannot offer.
+ * It does NOT fit several machines, where each one would hold a different half
+ * of the sessions.
+ */
+export interface FileDriverOptions {
+  /** Directory the session files live in. Created if missing. */
+  location: string
+}
+
+export class FileDriver implements SessionDriver {
+  readonly #location: string
+
+  constructor(options: FileDriverOptions) {
+    this.#location = path.resolve(options.location)
+    fs.mkdirSync(this.#location, { recursive: true })
+  }
+
+  /**
+   * The file backing a session id.
+   *
+   * The id is HASHED, never used as a filename: it arrives from a cookie, so a
+   * value like `../../etc/passwd` would otherwise choose the path. A hash also
+   * keeps the name a fixed, filesystem-safe length whatever the id looks like.
+   */
+  #pathFor(sessionId: string): string {
+    const name = createHash('sha256').update(sessionId).digest('hex')
+    return path.join(this.#location, `${name}.json`)
+  }
+
+  async read(sessionId: string): Promise<Record<string, unknown>> {
+    let raw: string
+    try {
+      raw = await fs.promises.readFile(this.#pathFor(sessionId), 'utf8')
+    } catch {
+      return {}
+    }
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (typeof parsed !== 'object' || parsed === null) return {}
+      const entry = parsed as { expiresAt?: number; data?: Record<string, unknown> }
+      if (typeof entry.expiresAt === 'number' && entry.expiresAt < Date.now()) {
+        await this.destroy(sessionId)
+        return {}
+      }
+      return entry.data ?? {}
+    } catch {
+      // A truncated or hand-edited file is a session we cannot trust; treat it
+      // as absent rather than handing a half-parsed object to the app.
+      return {}
+    }
+  }
+
+  async write(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
+    // otherwise leave a truncated file, and the user would be silently logged
+    // out. `rename` within one directory is atomic.
+    const temp = `${file}.${process.pid}.tmp`
+    await fs.promises.writeFile(temp, payload, { encoding: 'utf8', mode: 0o600 })
+    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)
+    if (Object.keys(data).length === 0) return
+    await this.write(sessionId, data, ttl)
+  }
+}

package/src/session/drivers/MemoryDriver.ts

@@ -1,9 +1,33 @@
-import type { SessionDriver } from '../Session.js'
+import type { SessionDriverWithTagging, TaggedSession } from '../Session.js'
 
+/** Sweep expired entries once the store reaches this size. */
 const SWEEP_THRESHOLD = 1000
 
-export class MemoryDriver implements SessionDriver {
+/**
+ * Hard cap on live sessions.
+ *
+ * The sweep alone only removes EXPIRED entries, so within the TTL window
+ * nothing bounded growth: anyone able to request a page could mint sessions
+ * until the process ran out of memory, without ever logging in. Past the cap
+ * the oldest sessions are dropped — a bounded store that forgets is strictly
+ * better than an unbounded one that dies.
+ */
+const DEFAULT_MAX_ENTRIES = 10_000
+
+export interface MemoryDriverOptions {
+  /** Maximum live sessions kept in memory. Default 10 000. */
+  maxEntries?: number
+}
+
+export class MemoryDriver implements SessionDriverWithTagging {
   #store: Map<string, { data: Record<string, unknown>; expiresAt: number }> = new Map()
+  /** user id → the sessions tagged with it. */
+  #tags: Map<string, Set<string>> = new Map()
+  readonly #maxEntries: number
+
+  constructor(options: MemoryDriverOptions = {}) {
+    this.#maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES)
+  }
 
   async read(sessionId: string): Promise<Record<string, unknown>> {
     const entry = this.#store.get(sessionId)
@@ -21,11 +45,26 @@ export class MemoryDriver implements SessionDriver {
         if (entry.expiresAt < now) this.#store.delete(id)
       }
     }
+    // Re-inserting moves the key to the end, so eviction order stays "oldest
+    // written first" rather than "oldest ever seen".
+    this.#store.delete(sessionId)
     this.#store.set(sessionId, { data, expiresAt: Date.now() + ttl * 1000 })
+    // Sweeping may have freed nothing — every session can be live and unexpired.
+    while (this.#store.size > this.#maxEntries) {
+      const oldest = this.#store.keys().next()
+      if (oldest.done) break
+      this.#store.delete(oldest.value)
+    }
   }
 
   async destroy(sessionId: string): Promise<void> {
     this.#store.delete(sessionId)
+    // Drop the tags too: a destroyed session left in the index would be
+    // reported as an active device forever.
+    for (const [userId, ids] of this.#tags) {
+      if (!ids.delete(sessionId)) continue
+      if (ids.size === 0) this.#tags.delete(userId)
+    }
   }
 
   async touch(sessionId: string, ttl: number): Promise<void> {
@@ -34,4 +73,38 @@ export class MemoryDriver implements SessionDriver {
       entry.expiresAt = Date.now() + ttl * 1000
     }
   }
+
+  async tag(sessionId: string, userId: string | number): Promise<void> {
+    const key = String(userId)
+    const ids = this.#tags.get(key) ?? new Set<string>()
+    ids.add(sessionId)
+    this.#tags.set(key, ids)
+  }
+
+  async untag(sessionId: string, userId: string | number): Promise<void> {
+    const key = String(userId)
+    const ids = this.#tags.get(key)
+    if (!ids) return
+    ids.delete(sessionId)
+    if (ids.size === 0) this.#tags.delete(key)
+  }
+
+  async tagged(userId: string | number): Promise<TaggedSession[]> {
+    const ids = this.#tags.get(String(userId))
+    if (!ids) return []
+    const now = Date.now()
+    const sessions: TaggedSession[] = []
+    for (const id of [...ids]) {
+      const entry = this.#store.get(id)
+      // An expired or evicted session is not an active device. Forget it here
+      // too, so the index does not grow with entries the store already lost.
+      if (!entry || entry.expiresAt < now) {
+        ids.delete(id)
+        continue
+      }
+      sessions.push({ id, data: { ...entry.data } })
+    }
+    if (ids.size === 0) this.#tags.delete(String(userId))
+    return sessions
+  }
 }

package/src/session/drivers/RedisDriver.ts

@@ -8,7 +8,7 @@
  * carries these four commands.
  */
 
-import type { SessionDriver } from '../Session.js'
+import type { SessionDriverWithTagging, TaggedSession } from '../Session.js'
 
 /** The commands a session needs. Compatible with ioredis and node-redis. */
 export interface SessionRedisClient {
@@ -16,6 +16,22 @@ export interface SessionRedisClient {
   set(key: string, value: string, ...args: unknown[]): Promise<unknown>
   del(key: string | string[]): Promise<number>
   expire(key: string, seconds: number): Promise<number>
+  /** Set commands, needed only for session tagging. Every real client has them. */
+  sadd?(key: string, ...members: string[]): Promise<number>
+  srem?(key: string, ...members: string[]): Promise<number>
+  smembers?(key: string): Promise<string[]>
+  exists?(key: string): Promise<number>
+}
+
+/** The set commands session tagging needs, over and above the base four. */
+const SET_COMMANDS = ['sadd', 'srem', 'smembers', 'exists'] as const
+
+/** A client that carries them. */
+type TaggingRedisClient = SessionRedisClient &
+  Required<Pick<SessionRedisClient, (typeof SET_COMMANDS)[number]>>
+
+function hasSetCommands(client: SessionRedisClient): client is TaggingRedisClient {
+  return SET_COMMANDS.every((command) => typeof client[command] === 'function')
 }
 
 /** Where the client comes from — resolved once, on the first request that needs it. */
@@ -28,7 +44,7 @@ export interface RedisSessionOptions {
   prefix?: string
 }
 
-export class RedisDriver implements SessionDriver {
+export class RedisDriver implements SessionDriverWithTagging {
   readonly #source: SessionRedisClientSource
   #resolved: SessionRedisClient | undefined
   #pending: Promise<SessionRedisClient> | undefined
@@ -64,6 +80,35 @@ export class RedisDriver implements SessionDriver {
     return `${this.#prefix}${sessionId}`
   }
 
+  /** Where the set of a user's session ids lives. */
+  #tagKey(userId: string | number): string {
+    return `${this.#prefix}tag:${userId}`
+  }
+
+  /**
+   * The client, narrowed to one that carries the set commands.
+   *
+   * They are optional on {@link SessionRedisClient} so a four-command shim
+   * still satisfies the store contract. A real client has them; a shim that
+   * does not gets told which command is missing, rather than a tag that
+   * silently does nothing and a "log out everywhere" that logs nobody out.
+   */
+  async #taggingClient(method: string): Promise<TaggingRedisClient> {
+    const client = await this.#client()
+    const missing = SET_COMMANDS.find((command) => typeof client[command] !== 'function')
+    if (missing !== undefined) {
+      throw new Error(
+        `session.${method}() needs the Redis \`${missing.toUpperCase()}\` command, which the configured client does not expose.`,
+      )
+    }
+    if (!hasSetCommands(client)) {
+      // Unreachable: `missing` already proved every command is there. The guard
+      // is what tells the type system so, without asserting it.
+      throw new Error(`session.${method}() could not narrow the Redis client.`)
+    }
+    return client
+  }
+
   /**
    * Unreadable payloads are treated as an absent session rather than thrown.
    * A corrupt value would otherwise 500 every request carrying that cookie,
@@ -99,6 +144,36 @@ export class RedisDriver implements SessionDriver {
     const client = await this.#client()
     await client.expire(this.#key(sessionId), ttl)
   }
+
+  async tag(sessionId: string, userId: string | number): Promise<void> {
+    const client = await this.#taggingClient('tag')
+    await client.sadd(this.#tagKey(userId), sessionId)
+  }
+
+  async untag(sessionId: string, userId: string | number): Promise<void> {
+    const client = await this.#taggingClient('untag')
+    await client.srem(this.#tagKey(userId), sessionId)
+  }
+
+  async tagged(userId: string | number): Promise<TaggedSession[]> {
+    const client = await this.#taggingClient('tagged')
+    const key = this.#tagKey(userId)
+    const ids = await client.smembers(key)
+    const sessions: TaggedSession[] = []
+    const stale: string[] = []
+    for (const id of ids) {
+      // A member whose session key expired is not an active device. Redis
+      // cannot expire set members individually, so the set is pruned here —
+      // otherwise it grows with every session the user ever opened.
+      if ((await client.exists(this.#key(id))) === 0) {
+        stale.push(id)
+        continue
+      }
+      sessions.push({ id, data: await this.read(id) })
+    }
+    if (stale.length > 0) await client.srem(key, ...stale)
+    return sessions
+  }
 }
 
 function isPlainRecord(value: unknown): value is Record<string, unknown> {

package/src/session/templateTags.ts

@@ -0,0 +1,124 @@
+/**
+ * The flash-message tags AdonisJS's session publishes to templates.
+ *
+ * A migrated template keeps writing:
+ *
+ *   @error('email')<p>{{ $message }}</p>@enderror
+ *   @errors<ul>@each(m in $messages)<li>{{ m }}</li>@endeach</ul>@enderrors
+ *   @inputError('email')@each(m in $messages)<i>{{ m }}</i>@endeach@endinputError
+ *   @flashMessage('notice')<p>{{ $message }}</p>@endflashMessage
+ *
+ * Each renders its body only when the message exists, and binds it under the
+ * name upstream uses (`$message` / `$messages`) — bound into the BODY's scope,
+ * so it does not leak past the tag.
+ *
+ * The values come from the `flashMessages` store the session middleware shares
+ * into `ctx.view`; the tag reads it out of the render scope.
+ */
+
+/** The single surface these tags need of a template engine. */
+export interface TemplateTagEngine {
+  registerTag(tag: {
+    tagName: string
+    block: boolean
+    seekable: boolean
+    compile(
+      parser: unknown,
+      buffer: { writeRaw(text: string): void },
+      token: {
+        properties: { jsArg: string }
+        renderBody(locals?: Readonly<Record<string, unknown>>): string | Promise<string>
+        evaluate(expression: string): unknown
+      },
+    ): void | Promise<void>
+  }): void
+}
+
+/** The bag shape the session shares — matches `ReadOnlyValuesStore`. */
+interface FlashStore {
+  get(path: string | readonly string[], defaultValue?: unknown): unknown
+  has(path: string | readonly string[]): boolean
+}
+
+function isFlashStore(value: unknown): value is FlashStore {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'get') === 'function' &&
+    typeof Reflect.get(value, 'has') === 'function'
+  )
+}
+
+/**
+ * Register `@error`, `@errors`, `@inputError` and `@flashMessage` on `engine`.
+ *
+ * Safe to call when no session ran: a template rendered outside a request finds
+ * no store in scope and every tag renders nothing, rather than throwing.
+ */
+export function registerSessionTemplateTags(engine: TemplateTagEngine): void {
+  /** The shared store, or undefined outside a request. */
+  const storeOf = (evaluate: (expr: string) => unknown): FlashStore | undefined => {
+    const value = evaluate("typeof flashMessages === 'undefined' ? undefined : flashMessages")
+    return isFlashStore(value) ? value : undefined
+  }
+
+  engine.registerTag({
+    tagName: 'flashMessage',
+    block: true,
+    seekable: true,
+    async compile(_parser, buffer, token) {
+      const store = storeOf(token.evaluate)
+      if (store === undefined) return
+      const key = token.evaluate(token.properties.jsArg)
+      if (typeof key !== 'string' || !store.has(key)) return
+      buffer.writeRaw(await token.renderBody({ $message: store.get(key) }))
+    },
+  })
+
+  engine.registerTag({
+    tagName: 'error',
+    block: true,
+    seekable: true,
+    async compile(_parser, buffer, token) {
+      const store = storeOf(token.evaluate)
+      if (store === undefined) return
+      const field = token.evaluate(token.properties.jsArg)
+      if (typeof field !== 'string') return
+      const path = ['errorsBag', field]
+      if (!store.has(path)) return
+      buffer.writeRaw(await token.renderBody({ $message: store.get(path) }))
+    },
+  })
+
+  engine.registerTag({
+    tagName: 'errors',
+    block: true,
+    // `@errors` takes no argument, exactly as upstream declares it.
+    seekable: false,
+    async compile(_parser, buffer, token) {
+      const store = storeOf(token.evaluate)
+      if (store === undefined || !store.has('errorsBag')) return
+      buffer.writeRaw(await token.renderBody({ $messages: store.get('errorsBag') }))
+    },
+  })
+
+  engine.registerTag({
+    tagName: 'inputError',
+    block: true,
+    seekable: true,
+    async compile(_parser, buffer, token) {
+      const store = storeOf(token.evaluate)
+      if (store === undefined) return
+      const field = token.evaluate(token.properties.jsArg)
+      if (typeof field !== 'string') return
+      const bag = store.get('inputErrorsBag', {})
+      const messages =
+        typeof bag === 'object' && bag !== null && Object.hasOwn(bag, field)
+          ? Reflect.get(bag, field)
+          : undefined
+      // Upstream gates on truthiness, so an empty list renders nothing.
+      if (!messages) return
+      buffer.writeRaw(await token.renderBody({ $messages: messages }))
+    },
+  })
+}