@c9up/ream 0.1.6 → 0.1.8

package/src/http/Request.ts

@@ -55,6 +55,7 @@ export class Request {
   #parsedQs: Dict<unknown> | undefined
   #merged: Dict<unknown> | undefined
   #files: Map<string, import('../bodyparser/MultipartFile.js').MultipartFile[]> = new Map()
+  #validated: unknown
 
   /**
    * CSRF token for this request (AdonisJS idiom: `request.csrfToken`). Seeded
@@ -376,6 +377,25 @@ export class Request {
     this.#merged = undefined // reset merged cache
   }
 
+  /**
+   * @internal Store the validated + transformed payload (called by the
+   * validation middleware after a route validator passes).
+   */
+  setValidated(data: unknown): void {
+    this.#validated = data
+  }
+
+  /**
+   * The validated + coerced payload produced by the route's `.validate()`
+   * validator, or `undefined` when the route declares no validator. Prefer
+   * this over `body()` in a validated handler — it carries the sanitized,
+   * type-coerced values, not the raw input. Returns `unknown`; narrow it at
+   * the call site (the validator already guaranteed the shape).
+   */
+  validated(): unknown {
+    return this.#validated
+  }
+
   #ensureParsedBody(): void {
     if (this.#parsedBody !== undefined) return
     const raw = this.#raw.body

package/src/index.ts

@@ -25,7 +25,7 @@ export {
   Exception,
   ExceptionHandler,
 } from './http/Exception.js'
-export type { AuthState, RouteInfo } from './http/HttpContext.js'
+export type { Authorizer, AuthState, RouteInfo } from './http/HttpContext.js'
 export { HttpContext } from './http/HttpContext.js'
 export { RedirectBuilder } from './http/RedirectBuilder.js'
 export type { RawRequest } from './http/Request.js'
@@ -260,4 +260,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.1.6'
+export const VERSION = '0.1.7'

package/src/middleware/Pipeline.ts

@@ -12,7 +12,7 @@
  */
 
 import { ReamError } from '../errors/ReamError.js'
-import { E_FORBIDDEN, E_UNAUTHORIZED } from '../http/Exception.js'
+import { E_FORBIDDEN, E_UNAUTHORIZED, E_VALIDATION_ERROR } from '../http/Exception.js'
 import type { HttpContext } from '../http/HttpContext.js'
 
 export type MiddlewareFunction = (
@@ -20,6 +20,15 @@ export type MiddlewareFunction = (
   next: () => Promise<void>,
 ) => Promise<void> | void
 
+/**
+ * Structural contract for a route validator. A `@c9up/rune` schema matches this
+ * shape, so ream stays decoupled from the validation engine — any object with a
+ * `validate(data)` returning `{ valid, errors, data? }` works.
+ */
+export interface RuntimeValidator {
+  validate(data: unknown): { valid: boolean; errors: unknown[]; data?: unknown }
+}
+
 /** Named middleware registry. */
 export class MiddlewareRegistry {
   #global: MiddlewareFunction[] = []
@@ -50,15 +59,29 @@ export class MiddlewareRegistry {
     namedMiddleware: string[],
     inlineMiddleware: MiddlewareFunction[],
     handler: MiddlewareFunction,
-    options?: { guards?: string[]; roles?: string[]; permissions?: string[] },
+    options?: {
+      guards?: string[]
+      roles?: string[]
+      permissions?: string[]
+      validators?: RuntimeValidator[]
+    },
   ): MiddlewareFunction {
     const stack: MiddlewareFunction[] = [
       // 1. Global middleware
       ...this.#global,
-      // 2. Named middleware
-      ...namedMiddleware
-        .map((name) => this.#named.get(name))
-        .filter((mw): mw is MiddlewareFunction => mw !== undefined),
+      // 2. Named middleware — an unknown name is a hard error, NOT a silent
+      // skip: a typo'd `.middleware('auht')` must never run the route
+      // unprotected with zero diagnostics.
+      ...namedMiddleware.map((name) => {
+        const mw = this.#named.get(name)
+        if (mw === undefined) {
+          throw new Error(
+            `[E_MIDDLEWARE_NOT_FOUND] Named middleware '${name}' is not registered. ` +
+              `Registered: ${[...this.#named.keys()].join(', ') || '(none)'}`,
+          )
+        }
+        return mw
+      }),
       // 3. Inline middleware
       ...inlineMiddleware,
       // 4. Guard enforcement (throws exceptions instead of setting response)
@@ -67,6 +90,11 @@ export class MiddlewareRegistry {
       (options?.permissions?.length ?? 0) > 0
         ? [createGuardMiddleware(options?.guards ?? [], options?.roles, options?.permissions)]
         : []),
+      // 4b. Validation — runs AFTER auth (so unauthenticated requests 401 before
+      // the body is inspected) and BEFORE the handler.
+      ...((options?.validators?.length ?? 0) > 0
+        ? [createValidationMiddleware(options?.validators ?? [])]
+        : []),
       // 5. Handler
       handler,
     ]
@@ -114,8 +142,13 @@ function createGuardMiddleware(
       throw new E_UNAUTHORIZED()
     }
 
+    // Auth providers may expose roles/permissions at the top level OR nested
+    // under `user` (e.g. @c9up/warden sets `ctx.auth.user.roles`). Read both so
+    // route-level `.role()`/`.permission()` work regardless of the provider's
+    // shape — reading only the top level silently denied every authenticated
+    // user when warden was wired.
     if (roles && roles.length > 0) {
-      const userRoles = ctx.auth.roles ?? []
+      const userRoles = ctx.auth.roles ?? ctx.auth.user?.roles ?? []
       const hasAnyRole = roles.some((r) => userRoles.includes(r))
       if (!hasAnyRole) {
         throw new E_FORBIDDEN('Insufficient role', roles)
@@ -123,7 +156,7 @@ function createGuardMiddleware(
     }
 
     if (permissions && permissions.length > 0) {
-      const userPerms = ctx.auth.permissions ?? []
+      const userPerms = ctx.auth.permissions ?? ctx.auth.user?.permissions ?? []
       if (!permissions.every((p) => userPerms.includes(p))) {
         throw new E_FORBIDDEN('Insufficient permissions', permissions)
       }
@@ -133,4 +166,24 @@ function createGuardMiddleware(
   }
 }
 
+/**
+ * Validation enforcement middleware. Runs each resolved route validator against
+ * the request body; the first failure throws `E_VALIDATION_ERROR` (422). On
+ * success the sanitized/coerced payload is stored on `request.validated()`.
+ */
+function createValidationMiddleware(validators: RuntimeValidator[]): MiddlewareFunction {
+  return async (ctx, next) => {
+    for (const validator of validators) {
+      const result = validator.validate(ctx.request.body())
+      if (!result.valid) {
+        throw new E_VALIDATION_ERROR(result.errors)
+      }
+      if (result.data !== undefined) {
+        ctx.request.setValidated(result.data)
+      }
+    }
+    await next()
+  }
+}
+
 export { compose }

package/src/router/Router.ts

@@ -5,6 +5,7 @@
  */
 
 import type { HttpContext } from '../http/HttpContext.js'
+import { safeDecodeURIComponent } from '../http/urlDecode.js'
 import type { MiddlewareFunction } from '../middleware/Pipeline.js'
 import type { MiddlewareEntry } from '../server/Server.js'
 import { resolveMiddlewareEntry } from '../server/Server.js'
@@ -120,7 +121,21 @@ export class RouteBuilder {
     return this
   }
 
-  /** Attach a validator. */
+  /**
+   * Validate the request body against a named validator. At request time the
+   * kernel resolves the validator from the IoC container under the token
+   * `validator:<name>` and runs it after the auth guards and before the handler;
+   * a failure short-circuits with `422 E_VALIDATION_ERROR` and the validated,
+   * coerced payload is exposed on `ctx.request.validated()`. The same name also
+   * feeds the OpenAPI generator's requestBody schema.
+   *
+   * Register the validator (any object with `validate(data) => { valid, errors,
+   * data? }`, e.g. a `@c9up/rune` schema):
+   *
+   *     container.singleton('validator:createUser', () => schema({ ... }))
+   *
+   * An unregistered name is a hard error — validation is never silently skipped.
+   */
   validate(validator: string): this {
     this.#route.validators.push(validator)
     return this
@@ -572,6 +587,13 @@ export class Router {
       }
     }
 
+    // HEAD falls back to the matching GET route (RFC 9110 §9.3.2 semantics —
+    // same headers, no body). Without this, `curl -I` and LB health probes
+    // 404 on every GET-only route.
+    if (method === 'HEAD') {
+      return this.match('GET', path, host)
+    }
+
     return undefined
   }
 
@@ -592,9 +614,12 @@ export class Router {
     let url = route.path
     if (params) {
       for (const [key, value] of Object.entries(params)) {
-        url = url
-          .replace(`:${key}?`, encodeURIComponent(value))
-          .replace(`:${key}`, encodeURIComponent(value))
+        // Word-boundary substitution: a bare `.replace(':id')` would corrupt
+        // `:idx` (`/x/:idx` → `/x/42x`). The lookahead requires the param name
+        // to END at the placeholder boundary. Keys are validated identifiers
+        // in route paths, but escape defensively (caller-supplied object).
+        const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        url = url.replace(new RegExp(`:${escaped}\\??(?![\\w])`, 'g'), encodeURIComponent(value))
       }
     }
     // Strip remaining optional placeholders (`:name?` segments not provided).
@@ -617,9 +642,17 @@ export class Router {
     return [...this.#routes]
   }
 
-  /** Clear all registered routes (used by hot-reload). */
+  /**
+   * Clear all registered routes AND registries (used by hot-reload). Router
+   * middleware, named middleware, and global matchers are reset too — the
+   * preloads that registered them re-run on reload, so keeping them would
+   * accumulate duplicates (middleware executing N+1 times after N reloads).
+   */
   clear(): void {
     this.#routes = []
+    this.#routerMiddleware = []
+    this.#namedMiddleware.clear()
+    this.#globalMatchers = {}
     this.#indexDirty = true
   }
 
@@ -660,6 +693,10 @@ export class Router {
       const matcher = matcherMap[param]
       if (!matcher) continue
       const regex = matcher instanceof RegExp ? matcher : matcher.pattern
+      // A user-supplied /g or /y regex is stateful (`lastIndex` advances on
+      // match) — without a reset, the same URL alternates match/no-match
+      // across requests. Reset before every test.
+      if (regex.global || regex.sticky) regex.lastIndex = 0
       if (!regex.test(value)) return false
     }
     return true
@@ -684,12 +721,17 @@ function matchPath(pattern: string, actual: string): Record<string, string> | nu
     for (let i = 0; i < wildcardIdx; i++) {
       const part = patternParts[i]
       if (part.startsWith(':')) {
-        params[part.substring(1)] = actualParts[i]
+        params[part.substring(1)] = safeDecodeURIComponent(actualParts[i])
       } else if (part !== actualParts[i]) {
         return null
       }
     }
-    params['*'] = actualParts.slice(wildcardIdx).join('/')
+    // Decode per segment, then rejoin — an encoded `/` inside a segment stays
+    // a value character, the path structure was already split on raw `/`.
+    params['*'] = actualParts
+      .slice(wildcardIdx)
+      .map((s) => safeDecodeURIComponent(s))
+      .join('/')
     return params
   }
 
@@ -708,7 +750,10 @@ function matchPath(pattern: string, actual: string): Record<string, string> | nu
     if (part.startsWith(':')) {
       const paramName = isOptional ? part.slice(1, -1) : part.substring(1)
       if (i < actualParts.length) {
-        params[paramName] = actualParts[i]
+        // Percent-decode the captured segment (query strings already are) so
+        // `/users/Jos%C3%A9` yields `José` and matchers test the real value.
+        // safeDecode falls back to the raw segment on malformed input.
+        params[paramName] = safeDecodeURIComponent(actualParts[i])
       }
       // Optional param with no actual part — skip (param not set)
     } else if (i < actualParts.length && part !== actualParts[i]) {

package/src/rpc/RpcProvider.ts

@@ -15,6 +15,7 @@
  * @implements Story 24.1, 24.2
  */
 
+import { ReamError } from '../errors/ReamError.js'
 import type { HttpContext } from '../http/HttpContext.js'
 import type { AppContext } from '../Provider.js'
 import { Provider } from '../Provider.js'
@@ -40,8 +41,19 @@ export class RpcProvider extends Provider {
   }
 
   override register(): void {
-    this.rpc.useContainer(this.app.container)
-    this.app.container.singleton('rpc', () => this.rpc)
+    const container = this.app.container
+    if (container.has('rpc')) {
+      if (container.resolve('rpc') === this.rpc) return // re-register is idempotent
+      throw new ReamError(
+        'RPC_PROVIDER_ALREADY_REGISTERED',
+        "Container token 'rpc' is already bound to a different instance",
+        {
+          hint: 'Only one RpcProvider can own the rpc binding. Remove the duplicate provider from your reamrc.ts.',
+        },
+      )
+    }
+    this.rpc.useContainer(container)
+    container.singleton('rpc', () => this.rpc)
   }
 
   override async boot(): Promise<void> {

package/src/rpc/RpcRouter.ts

@@ -12,9 +12,21 @@
  */
 
 import type { HttpContext } from '../http/HttpContext.js'
+import type { MiddlewareRegistry, RuntimeValidator } from '../middleware/Pipeline.js'
+import { compose } from '../middleware/Pipeline.js'
 
 export type RpcHandler = (ctx: HttpContext, params: unknown) => Promise<unknown> | unknown
 
+/**
+ * Subset of the IoC container RpcRouter needs: resolve `namespace()` controllers,
+ * the shared `'middleware'` registry, and `validator:<name>` schemas.
+ */
+interface RpcContainer {
+  make<T>(target: new (...args: unknown[]) => T): T
+  resolve<T>(token: string): T
+  has(token: string): boolean
+}
+
 export interface RpcMethodDefinition {
   name: string
   handler: RpcHandler
@@ -60,13 +72,17 @@ export class RpcMethodBuilder {
 
 interface RpcErrorResponse {
   jsonrpc: '2.0'
-  error: { code: number; message: string }
+  error: { code: number; message: string; data?: unknown }
   id: unknown
 }
 
 /** Build a JSON-RPC 2.0 error envelope. */
-function rpcError(code: number, message: string, id: unknown): RpcErrorResponse {
-  return { jsonrpc: '2.0', error: { code, message }, id }
+function rpcError(code: number, message: string, id: unknown, data?: unknown): RpcErrorResponse {
+  return {
+    jsonrpc: '2.0',
+    error: data === undefined ? { code, message } : { code, message, data },
+    id,
+  }
 }
 
 type ParsedRpcRequest =
@@ -91,6 +107,24 @@ function parseRpcRequest(request: unknown): ParsedRpcRequest {
   return { ok: true, method, params, id }
 }
 
+/**
+ * A JSON-RPC notification is a well-formed request with NO `id` member. The spec
+ * (§4.1) says the server MUST NOT reply to one — it still runs for side-effects.
+ * A malformed object (no method / wrong version) is NOT a notification: it gets
+ * an `id:null` error response since the server can't tell the client's intent.
+ */
+function isNotification(request: unknown): boolean {
+  return (
+    !!request &&
+    typeof request === 'object' &&
+    'jsonrpc' in request &&
+    request.jsonrpc === '2.0' &&
+    'method' in request &&
+    typeof request.method === 'string' &&
+    !('id' in request)
+  )
+}
+
 /**
  * Enforce the method's guards/roles/permissions against the request auth state.
  * Returns the JSON-RPC error code+message to reject with, or undefined when the
@@ -105,13 +139,15 @@ function checkRpcAuthorization(
     return { code: -32003, message: 'Unauthorized' }
   }
   if (def.roles.length > 0) {
-    const userRoles = ctx.auth?.roles ?? []
+    // Warden nests roles/permissions under ctx.auth.user — mirror the HTTP path
+    // (Pipeline.ts createGuardMiddleware) so RPC role gates aren't fail-closed-dead.
+    const userRoles = ctx.auth?.roles ?? ctx.auth?.user?.roles ?? []
     if (!def.roles.some((r: string) => userRoles.includes(r))) {
       return { code: -32003, message: 'Insufficient role' }
     }
   }
   if (def.permissions.length > 0) {
-    const userPerms = ctx.auth?.permissions ?? []
+    const userPerms = ctx.auth?.permissions ?? ctx.auth?.user?.permissions ?? []
     if (!def.permissions.every((p: string) => userPerms.includes(p))) {
       return { code: -32003, message: 'Insufficient permissions' }
     }
@@ -122,7 +158,7 @@ function checkRpcAuthorization(
 export class RpcRouter {
   #methods: Map<string, RpcMethodDefinition> = new Map()
   #groupConfig: { guards: string[]; roles: string[]; middleware: string[] } | null = null
-  #container?: { make<T>(target: new (...args: unknown[]) => T): T }
+  #container?: RpcContainer
 
   /**
    * Set the IoC container used to resolve `namespace()` controllers — mirrors
@@ -130,7 +166,7 @@ export class RpcRouter {
    * same way (fresh DI per call). Without a container, controllers fall back to
    * `new Controller()`.
    */
-  useContainer(container: { make<T>(target: new (...args: unknown[]) => T): T }): void {
+  useContainer(container: RpcContainer): void {
     this.#container = container
   }
 
@@ -178,8 +214,13 @@ export class RpcRouter {
       roles: [],
       middleware: config.middleware ?? [],
     }
-    callback(this)
-    this.#groupConfig = prevConfig
+    // try/finally so a throwing callback can't leave #groupConfig stuck at the
+    // group's value and leak its guards/middleware onto sibling registrations.
+    try {
+      callback(this)
+    } finally {
+      this.#groupConfig = prevConfig
+    }
   }
 
   /** Handle an incoming JSON-RPC request. */
@@ -197,18 +238,58 @@ export class RpcRouter {
         return
       }
       // Note: batch items share the same ctx (auth state). Each is processed sequentially.
+      // Notifications still run (side-effects) but their result is omitted from
+      // the reply per JSON-RPC §4.1.
       const results: unknown[] = []
       for (const req of body) {
-        results.push(await this.#processOne(ctx, req))
+        const r = await this.#processOne(ctx, req)
+        if (!isNotification(req)) results.push(r)
+      }
+      // An all-notification batch produces no response body (spec: no reply).
+      if (results.length === 0) {
+        ctx.response.status(204).send('')
+        return
       }
       ctx.response.status(200).json(results)
       return
     }
 
     const result = await this.#processOne(ctx, body)
+    // A notification runs for side-effects but MUST NOT receive a reply.
+    if (isNotification(body)) {
+      ctx.response.status(204).send('')
+      return
+    }
     ctx.response.status(200).json(result)
   }
 
+  /**
+   * Run the method's declared named middleware (resolved from the shared
+   * `'middleware'` registry) onion-style before the handler. Guards/auth
+   * middleware deny by THROWING — #processOne maps the throw to a JSON-RPC
+   * error. An unknown middleware name is a hard error, never a silent skip.
+   * (RPC shares one ctx per batch, so response-writing/short-circuit middleware
+   * are unsupported — deny by throwing.)
+   */
+  async #runMiddleware(ctx: HttpContext, names: string[]): Promise<void> {
+    const registry = this.#container?.has('middleware')
+      ? this.#container.resolve<MiddlewareRegistry>('middleware')
+      : undefined
+    if (!registry) {
+      throw new Error(
+        `[E_MIDDLEWARE_NOT_FOUND] RPC middleware [${names.join(', ')}] is declared but no middleware registry is wired into the RpcRouter.`,
+      )
+    }
+    const fns = names.map((name) => {
+      const mw = registry.get(name)
+      if (!mw) {
+        throw new Error(`[E_MIDDLEWARE_NOT_FOUND] Named middleware '${name}' is not registered.`)
+      }
+      return mw
+    })
+    await compose(fns)(ctx, async () => {})
+  }
+
   async #processOne(ctx: HttpContext, request: unknown): Promise<unknown> {
     const parsed = parseRpcRequest(request)
     if (!parsed.ok) return parsed.response
@@ -221,7 +302,30 @@ export class RpcRouter {
       const denied = checkRpcAuthorization(ctx, def)
       if (denied) return rpcError(denied.code, denied.message, id)
 
-      const result = await def.handler(ctx, params)
+      // Run declared named middleware (e.g. guards) — they throw to deny, mapped
+      // to a JSON-RPC error by the catch below.
+      if (def.middleware.length > 0) {
+        await this.#runMiddleware(ctx, def.middleware)
+      }
+
+      // Run the declared validator against params. A declared-but-unregistered
+      // validator is a hard error — never silently skip validation.
+      let effectiveParams = params
+      if (def.validator) {
+        const token = `validator:${def.validator}`
+        if (!this.#container?.has(token)) {
+          return rpcError(
+            -32603,
+            `Validator '${def.validator}' is not registered (bind container.singleton('${token}', () => schema)).`,
+            id,
+          )
+        }
+        const outcome = this.#container.resolve<RuntimeValidator>(token).validate(params)
+        if (!outcome.valid) return rpcError(-32602, 'Invalid params', id, outcome.errors)
+        effectiveParams = outcome.data ?? params
+      }
+
+      const result = await def.handler(ctx, effectiveParams)
       return { jsonrpc: '2.0', result, id }
     } catch (err) {
       // Don't leak internal error details to caller

package/src/scheduler/ScheduleProvider.ts

@@ -35,6 +35,9 @@ export interface ScheduleProviderOptions {
   scheduler?: Scheduler
 }
 
+/** Prevents two ScheduleProvider instances from ticking simultaneously (two apps, same process). */
+let activeProvider: ScheduleProvider | undefined
+
 export class ScheduleProvider extends Provider {
   readonly scheduler: Scheduler
   #booted = false
@@ -168,10 +171,17 @@ export class ScheduleProvider extends Provider {
   }
 
   override async start(): Promise<void> {
+    if (activeProvider !== undefined && activeProvider !== this) {
+      // A previous app's scheduler is still running — stop it before this one starts,
+      // otherwise every @Schedule task fires twice per tick.
+      activeProvider.scheduler.stop()
+    }
+    activeProvider = this
     this.scheduler.start()
   }
 
   override async shutdown(): Promise<void> {
+    if (activeProvider === this) activeProvider = undefined
     this.scheduler.stop()
   }
 }

package/src/scheduler/locks/MemoryLockBackend.ts

@@ -81,5 +81,3 @@ export class MemoryLockBackend implements LockBackend {
     return this.#locks.size
   }
 }
-
-export default MemoryLockBackend

package/src/services/app.ts

@@ -16,6 +16,15 @@ export function setApp(app: Application): void {
   instance = app
 }
 
+/**
+ * @internal Unset the locator IF it still points at `app` (called by
+ * Ignitor.stop()). Ownership-guarded: when a second Ignitor rebound the
+ * locator, the older app's stop() must not tear down the newer binding.
+ */
+export function clearApp(app: Application): void {
+  if (instance === app) instance = undefined
+}
+
 const app: Application = new Proxy({} as Application, {
   get(_target, prop) {
     if (!instance) {

package/src/services/router.ts

@@ -17,6 +17,14 @@ export function setRouter(router: Router): void {
   instance = router
 }
 
+/**
+ * @internal Unset the locator IF it still points at `router` (called by
+ * Ignitor.stop()). Ownership-guarded — see services/app.ts.
+ */
+export function clearRouter(router: Router): void {
+  if (instance === router) instance = undefined
+}
+
 /** @internal Get the router instance directly. */
 export function getRouter(): Router | undefined {
   return instance

package/src/services/server.ts

@@ -16,6 +16,14 @@ export function setServer(server: Server): void {
   instance = server
 }
 
+/**
+ * @internal Unset the locator IF it still points at `server` (called by
+ * Ignitor.stop()). Ownership-guarded — see services/app.ts.
+ */
+export function clearServer(server: Server): void {
+  if (instance === server) instance = undefined
+}
+
 /** @internal Get the server instance directly. */
 export function getServer(): Server | undefined {
   return instance

package/src/session/SessionMiddleware.ts

@@ -78,6 +78,12 @@ export default class SessionMiddleware {
       const shouldEmit = session.isDirty() || (rolling && hadIncomingCookie)
       if (shouldEmit) {
         const encoded = this.#cookieDriver.encode(session.toJSON())
+        if (encoded.length > 4096) {
+          process.stderr.write(
+            `[session] Cookie session exceeds 4096 bytes (${encoded.length}). ` +
+              'Switch to a server-side driver (memory/redis) or reduce session data.\n',
+          )
+        }
         ctx.response.cookie(cookieName, encoded, {
           maxAge: this.#config.clearWithBrowser ? undefined : maxAge,
           path: '/',

package/src/session/drivers/MemoryDriver.ts

@@ -1,27 +1,35 @@
 import type { SessionDriver } from '../Session.js'
 
+const SWEEP_THRESHOLD = 1000
+
 export class MemoryDriver implements SessionDriver {
-  private store: Map<string, { data: Record<string, unknown>; expiresAt: number }> = new Map()
+  #store: Map<string, { data: Record<string, unknown>; expiresAt: number }> = new Map()
 
   async read(sessionId: string): Promise<Record<string, unknown>> {
-    const entry = this.store.get(sessionId)
+    const entry = this.#store.get(sessionId)
     if (!entry || entry.expiresAt < Date.now()) {
-      this.store.delete(sessionId)
+      this.#store.delete(sessionId)
       return {}
     }
     return { ...entry.data }
   }
 
   async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
-    this.store.set(sessionId, { data, expiresAt: Date.now() + ttl * 1000 })
+    if (this.#store.size >= SWEEP_THRESHOLD) {
+      const now = Date.now()
+      for (const [id, entry] of this.#store) {
+        if (entry.expiresAt < now) this.#store.delete(id)
+      }
+    }
+    this.#store.set(sessionId, { data, expiresAt: Date.now() + ttl * 1000 })
   }
 
   async destroy(sessionId: string): Promise<void> {
-    this.store.delete(sessionId)
+    this.#store.delete(sessionId)
   }
 
   async touch(sessionId: string, ttl: number): Promise<void> {
-    const entry = this.store.get(sessionId)
+    const entry = this.#store.get(sessionId)
     if (entry) {
       entry.expiresAt = Date.now() + ttl * 1000
     }