@furystack/rest-service 13.0.0 → 14.1.0

package/src/static-server-manager.spec.ts

@@ -1,224 +1,137 @@
-import { Injector } from '@furystack/inject'
-import { sleepAsync, usingAsync } from '@furystack/utils'
-import { ServerManager } from './server-manager.js'
-import { StaticServerManager } from './static-server-manager.js'
-import { describe, it, expect, vi } from 'vitest'
 import { getPort } from '@furystack/core/port-generator'
+import { createInjector } from '@furystack/inject'
+import { sleepAsync, usingAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import { useStaticFiles } from './helpers.js'
+import { HttpServerPoolToken } from './http-server-pool.js'
+import { buildStaticSiteServerApi } from './static-site-runtime.js'
 
-describe('StaticServerManager', () => {
+describe('useStaticFiles / buildStaticSiteServerApi', () => {
   describe('Top level routing', () => {
-    it('Should return a 404 without fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('responds 404 without a fallback', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
+        await useStaticFiles({ injector: i, baseUrl: '/', path: '.', port })
 
         const result = await fetch(`http://127.0.0.1:${port}/not-found.html`)
         expect(result.ok).toBe(false)
         expect(result.status).toBe(404)
-        expect(result?.headers.get('content-type')).toBe('text/plain')
-        const body = await result.text()
-        expect(body).toBe('Not found')
+        expect(result.headers.get('content-type')).toBe('text/plain')
+        expect(await result.text()).toBe('Not found')
       })
     })
 
-    it('Should return a fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('falls back to the configured file and returns its content-type', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
+        await useStaticFiles({
+          injector: i,
           baseUrl: '/',
           path: '.',
           fallback: 'package.json',
           port,
-          headers: {
-            'custom-header': 'custom-value',
-          },
+          headers: { 'custom-header': 'custom-value' },
         })
 
         const result = await fetch(`http://localhost:${port}/not-found.html`)
-
         expect(result.headers.get('content-type')).toBe('application/json')
         expect(result.headers.get('custom-header')).toBe('custom-value')
       })
     })
 
-    it('Should return a fallback for root files', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('falls back for the root url when no index exists', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
+        await useStaticFiles({
+          injector: i,
           baseUrl: '/',
           path: '.',
           fallback: 'package.json',
           port,
-          headers: {
-            'custom-header': 'custom-value',
-          },
+          headers: { 'custom-header': 'custom-value' },
         })
 
         const result = await fetch(`http://localhost:${port}`)
-
         expect(result.headers.get('content-type')).toBe('application/json')
         expect(result.headers.get('custom-header')).toBe('custom-value')
       })
     })
 
-    it('Should return a defined file from a root directory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('serves an existing file from the root directory', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-          headers: {
-            'custom-header': 'custom-value',
-          },
-        })
-
+        await useStaticFiles({ injector: i, baseUrl: '/', path: '.', port })
         const result = await fetch(`http://localhost:${port}/README.md`)
-
         expect(result.headers.get('content-type')).toBe('text/markdown')
-        expect(result.headers.get('custom-header')).toBe('custom-value')
       })
     })
 
-    it('Should return a defined file from a subdirectory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('serves files from subdirectories', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
-
+        await useStaticFiles({ injector: i, baseUrl: '/', path: '.', port })
         const result = await fetch(`http://localhost:${port}/packages/utils/README.md`)
-
         expect(result.headers.get('content-type')).toBe('text/markdown')
       })
     })
   })
 
   describe('Non-top level routing', () => {
-    it('Should not handle a request when the path is not matching', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('leaves requests outside the base url to the next api in the chain', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
+        const serverApi = await useStaticFiles({ injector: i, baseUrl: '/bundle', path: '.', port })
 
-        await staticServerManager.addStaticSite({
-          baseUrl: '/bundle',
-          path: '.',
-          port,
-        })
-
-        const server = [...injector.getInstance(ServerManager).servers.values()][0]
-
-        server.apis[0].onRequest = vi.fn()
+        const record = await i.get(HttpServerPoolToken).acquire({ port })
+        const onRequest = vi.fn()
+        // Swap in a spy to observe non-matching requests never reach the handler.
+        serverApi.onRequest = onRequest
+        record.apis[0] = serverApi
 
         fetch(`http://localhost:${port}/bundleToAnotherFolder/not-found.html`).catch(() => {
-          /** should fall, ignore */
+          // Expected to fail: the server has no matching API and drops the socket.
         })
-
         await sleepAsync(100)
-
-        expect(server.apis[0].onRequest).not.toHaveBeenCalled()
+        expect(onRequest).not.toHaveBeenCalled()
       })
     })
 
-    it('Should return a 404 without fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('returns 404 under a sub-base url when the file is missing and no fallback is set', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/bundle',
-          path: '.',
-          port,
-        })
+        await useStaticFiles({ injector: i, baseUrl: '/bundle', path: '.', port })
 
         const result = await fetch(`http://localhost:${port}/bundle/not-found.html`)
         expect(result.ok).toBe(false)
         expect(result.status).toBe(404)
         expect(result.headers.get('content-type')).toBe('text/plain')
-        const body = await result.text()
-        expect(body).toBe('Not found')
+        expect(await result.text()).toBe('Not found')
       })
     })
 
-    it('Should return a fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('serves the configured fallback under a sub-base url', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/bundle',
-          path: '.',
-          fallback: 'package.json',
-          port,
-        })
+        await useStaticFiles({ injector: i, baseUrl: '/bundle', path: '.', fallback: 'package.json', port })
 
         const result = await fetch(`http://localhost:${port}/bundle/not-found.html`)
-
         expect(result.headers.get('content-type')).toBe('application/json')
       })
     })
-
-    it('Should return a defined file from a root directory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
-        const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
-
-        const result = await fetch(`http://localhost:${port}/README.md`)
-
-        expect(result.headers.get('content-type')).toBe('text/markdown')
-      })
-    })
-
-    it('Should return a defined file from a subdirectory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
-        const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
-
-        const result = await fetch(`http://localhost:${port}/packages/utils/README.md`)
-
-        expect(result.headers.get('content-type')).toBe('text/markdown')
-      })
-    })
   })
 
   describe('shouldExec', () => {
-    it('Should NOT match for requests with not defined method', () => {
-      const staticServerManager = new StaticServerManager()
-      expect(staticServerManager.shouldExec('/')({ req: { url: '/' } })).toBe(false)
+    const api = (baseUrl: string) => buildStaticSiteServerApi({ baseUrl, path: '.', port: 0 })
+
+    it('does not match when the request method is missing', () => {
+      expect(api('/').shouldExec({ req: { url: '/' } as never, res: {} as never })).toBe(false)
     })
 
-    it('Should NOT match for non-GET requests', () => {
-      const staticServerManager = new StaticServerManager()
-      expect(staticServerManager.shouldExec('/')({ req: { method: 'POST', url: '/' } })).toBe(false)
+    it('does not match non-GET methods', () => {
+      expect(api('/').shouldExec({ req: { method: 'POST', url: '/' } as never, res: {} as never })).toBe(false)
     })
-    ;[
+
+    const positiveCases: Array<[string, string]> = [
       ['/', '/'],
       ['/', '/index.html'],
       ['/', '/subdir'],
@@ -228,22 +141,21 @@ describe('StaticServerManager', () => {
       ['/subdir', '/subdir/'],
       ['/subdir', '/subdir/file.js'],
       ['/subdir', '/subdir/s2/file.js'],
-    ].forEach(([root, url]) =>
-      it(`Should match for '${root}' root and '${url}' url`, () => {
-        const staticServerManager = new StaticServerManager()
-        const shouldExec = staticServerManager.shouldExec(root)({ req: { method: 'GET', url } })
-        expect(shouldExec).toBe(true)
+    ]
+    positiveCases.forEach(([baseUrl, url]) =>
+      it(`matches GET '${url}' against base '${baseUrl}'`, () => {
+        expect(api(baseUrl).shouldExec({ req: { method: 'GET', url } as never, res: {} as never })).toBe(true)
       }),
     )
 
-    it('Should not exec different paths for non-top level root directory', () => {
-      const staticServerManager = new StaticServerManager()
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/' } })).toBe(false)
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/other/index.html' } })).toBe(
+    it('does not match unrelated urls under a non-root base', () => {
+      const subdir = api('/subdir')
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/' } as never, res: {} as never })).toBe(false)
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/other/index.html' } as never, res: {} as never })).toBe(
         false,
       )
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/subdir2' } })).toBe(false)
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/subdir2/index.html' } })).toBe(
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/subdir2' } as never, res: {} as never })).toBe(false)
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/subdir2/index.html' } as never, res: {} as never })).toBe(
         false,
       )
     })

package/src/static-site-runtime.spec.ts

@@ -0,0 +1,39 @@
+import type { IncomingMessage, ServerResponse } from 'http'
+import { describe, expect, it } from 'vitest'
+import { buildStaticSiteServerApi } from './static-site-runtime.js'
+
+const makeRequest = (url: string | undefined, method: string | undefined = 'GET'): IncomingMessage =>
+  ({ url, method, headers: {} }) as unknown as IncomingMessage
+
+// Full onRequest / sendFile behaviour (streaming, fallback, 404) is covered
+// end-to-end via `static-server-manager.spec.ts` which drives the real HTTP
+// pool. These tests cover the pure-function `shouldExec` gate which is
+// exercised by the server pool before any request is handed to the API.
+describe('buildStaticSiteServerApi / shouldExec', () => {
+  const api = buildStaticSiteServerApi({ baseUrl: '/static', path: '/tmp', port: 0 })
+
+  it('matches GET requests under the baseUrl', () => {
+    expect(api.shouldExec({ req: makeRequest('/static/index.html'), res: {} as ServerResponse })).toBe(true)
+  })
+
+  it('is case-insensitive about the method (GET only)', () => {
+    expect(api.shouldExec({ req: makeRequest('/static/a.html', 'get'), res: {} as ServerResponse })).toBe(true)
+  })
+
+  it('rejects non-GET methods', () => {
+    expect(api.shouldExec({ req: makeRequest('/static/index.html', 'POST'), res: {} as ServerResponse })).toBe(false)
+    expect(api.shouldExec({ req: makeRequest('/static/index.html', 'DELETE'), res: {} as ServerResponse })).toBe(false)
+  })
+
+  it('rejects URLs that do not match the baseUrl', () => {
+    expect(api.shouldExec({ req: makeRequest('/other/index.html'), res: {} as ServerResponse })).toBe(false)
+  })
+
+  it('rejects requests without a URL', () => {
+    expect(api.shouldExec({ req: makeRequest(undefined), res: {} as ServerResponse })).toBe(false)
+  })
+
+  it('never exposes an onUpgrade hook (static sites do not handle upgrades)', () => {
+    expect(api.onUpgrade).toBeUndefined()
+  })
+})

package/src/static-site-runtime.ts

@@ -0,0 +1,75 @@
+import { PathHelper } from '@furystack/utils'
+import { createReadStream } from 'fs'
+import { access, stat } from 'fs/promises'
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'http'
+import { join, normalize, sep } from 'path'
+import type { ServerApi } from './http-server-pool.js'
+import { getMimeForFile } from './mime-types.js'
+
+/**
+ * Options accepted by {@link buildStaticSiteServerApi} and
+ * {@link useStaticFiles}.
+ */
+export interface StaticServerOptions {
+  baseUrl: string
+  path: string
+  hostName?: string
+  port: number
+  fallback?: string
+  headers?: OutgoingHttpHeaders
+}
+
+const sendFile = async ({
+  fullPath,
+  headers,
+  res,
+}: {
+  fullPath: string
+  res: ServerResponse
+  headers?: OutgoingHttpHeaders
+}): Promise<void> => {
+  const { size } = await stat(fullPath)
+  await access(fullPath)
+  const head = {
+    ...headers,
+    'Content-Length': size,
+    'Content-Type': getMimeForFile(fullPath),
+  }
+  Object.entries(head).forEach(([key, value]) => res.setHeader(key, value))
+  await new Promise<void>((resolve, reject) =>
+    createReadStream(fullPath, { autoClose: true }).once('finish', resolve).once('error', reject).pipe(res),
+  )
+}
+
+/**
+ * Builds a {@link ServerApi} that serves files under `options.path` for every
+ * GET request whose URL matches `options.baseUrl`. Falls back to
+ * `options.fallback` (if set) for missing files, otherwise responds with 404.
+ */
+export const buildStaticSiteServerApi = (options: StaticServerOptions): ServerApi => {
+  const onRequest = async ({ req, res }: { req: IncomingMessage; res: ServerResponse }): Promise<void> => {
+    const extractedPath = PathHelper.extractPath(req.url as string, options.baseUrl)
+    const filePath = (extractedPath || '/').replaceAll('/', sep)
+    const fullPath = normalize(join(options.path, filePath))
+    try {
+      await sendFile({ fullPath, res, headers: options.headers })
+    } catch {
+      if (options.fallback) {
+        await sendFile({ fullPath: normalize(join(options.path, options.fallback)), res, headers: options.headers })
+        return
+      }
+      res.writeHead(404, { 'Content-Type': 'text/plain' })
+      res.end('Not found')
+    }
+  }
+
+  return {
+    shouldExec: ({ req }) =>
+      req.url !== undefined &&
+      req.method?.toUpperCase() === 'GET' &&
+      PathHelper.matchesBaseUrl(req.url, options.baseUrl)
+        ? true
+        : false,
+    onRequest,
+  }
+}

package/src/user-resolution-cache.spec.ts

@@ -0,0 +1,241 @@
+import type { User } from '@furystack/core'
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { HttpAuthenticationSettings, defaultHttpAuthenticationSettings } from './http-authentication-settings.js'
+import { resolveUserCacheKey, UserResolutionCache } from './user-resolution-cache.js'
+
+const testUser: User = { username: 'alice', roles: ['reader'] }
+const otherUser: User = { username: 'bob', roles: [] }
+
+describe('UserResolutionCache', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('resolve', () => {
+    it('returns the loader result on first call and reuses it on subsequent calls within TTL', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(async () => testUser)
+        const first = await cache.resolve('cookie:abc', loader)
+        const second = await cache.resolve('cookie:abc', loader)
+        expect(first).toBe(testUser)
+        expect(second).toBe(testUser)
+        expect(loader).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('treats distinct cache keys independently', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loaderA = vi.fn(async () => testUser)
+        const loaderB = vi.fn(async () => otherUser)
+        expect(await cache.resolve('cookie:a', loaderA)).toBe(testUser)
+        expect(await cache.resolve('cookie:b', loaderB)).toBe(otherUser)
+        expect(await cache.resolve('cookie:a', loaderA)).toBe(testUser)
+        expect(loaderA).toHaveBeenCalledTimes(1)
+        expect(loaderB).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('drops the entry once cacheTimeMs has elapsed', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 100,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(async () => testUser)
+        await cache.resolve('cookie:ttl', loader)
+        await vi.advanceTimersByTimeAsync(150)
+        await cache.resolve('cookie:ttl', loader)
+        expect(loader).toHaveBeenCalledTimes(2)
+      })
+    })
+
+    it('runs the loader on every call when ttl is 0', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 0,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(async () => testUser)
+        await cache.resolve('cookie:disabled', loader)
+        await cache.resolve('cookie:disabled', loader)
+        expect(loader).toHaveBeenCalledTimes(2)
+        expect(cache.size).toBe(0)
+      })
+    })
+
+    it('dedupes concurrent loaders for the same key', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi.fn(
+          () =>
+            new Promise<User>((resolve) => {
+              setTimeout(() => resolve(testUser), 100)
+            }),
+        )
+        const both = Promise.all([cache.resolve('cookie:dedupe', loader), cache.resolve('cookie:dedupe', loader)])
+        await vi.advanceTimersByTimeAsync(150)
+        const [a, b] = await both
+        expect(a).toBe(testUser)
+        expect(b).toBe(testUser)
+        expect(loader).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('rejects (without caching) when the loader throws', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loader = vi
+          .fn<() => Promise<User>>()
+          .mockRejectedValueOnce(new Error('boom'))
+          .mockResolvedValueOnce(testUser)
+        await expect(cache.resolve('cookie:err', loader)).rejects.toThrow('boom')
+        await expect(cache.resolve('cookie:err', loader)).resolves.toBe(testUser)
+        expect(loader).toHaveBeenCalledTimes(2)
+      })
+    })
+  })
+
+  describe('invalidate', () => {
+    it('drops the targeted entry only', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const loaderA = vi.fn(async () => testUser)
+        const loaderB = vi.fn(async () => otherUser)
+        await cache.resolve('cookie:a', loaderA)
+        await cache.resolve('cookie:b', loaderB)
+        cache.invalidate('cookie:a')
+        await cache.resolve('cookie:a', loaderA)
+        await cache.resolve('cookie:b', loaderB)
+        expect(loaderA).toHaveBeenCalledTimes(2)
+        expect(loaderB).toHaveBeenCalledTimes(1)
+      })
+    })
+  })
+
+  describe('invalidateAll', () => {
+    it('flushes every entry', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        await cache.resolve('cookie:a', async () => testUser)
+        await cache.resolve('cookie:b', async () => otherUser)
+        expect(cache.size).toBe(2)
+        cache.invalidateAll()
+        expect(cache.size).toBe(0)
+      })
+    })
+  })
+
+  describe('invalidateByUser', () => {
+    it('drops every cached session that resolved to the supplied username', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        const aliceLoaderA = vi.fn(async () => testUser)
+        const aliceLoaderB = vi.fn(async () => testUser)
+        const bobLoader = vi.fn(async () => otherUser)
+        await cache.resolve('cookie:alice-1', aliceLoaderA)
+        await cache.resolve('cookie:alice-2', aliceLoaderB)
+        await cache.resolve('cookie:bob-1', bobLoader)
+        expect(cache.size).toBe(3)
+
+        cache.invalidateByUser('alice')
+
+        expect(cache.size).toBe(1)
+        await cache.resolve('cookie:alice-1', aliceLoaderA)
+        await cache.resolve('cookie:alice-2', aliceLoaderB)
+        await cache.resolve('cookie:bob-1', bobLoader)
+        expect(aliceLoaderA).toHaveBeenCalledTimes(2)
+        expect(aliceLoaderB).toHaveBeenCalledTimes(2)
+        expect(bobLoader).toHaveBeenCalledTimes(1)
+      })
+    })
+
+    it('is a no-op when the username is unknown', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 30_000,
+        }))
+        const cache = i.get(UserResolutionCache)
+        await cache.resolve('cookie:alice-1', async () => testUser)
+        await cache.resolve('cookie:bob-1', async () => otherUser)
+        cache.invalidateByUser('charlie')
+        expect(cache.size).toBe(2)
+      })
+    })
+
+    it('is a no-op when caching is disabled (ttl = 0)', async () => {
+      await usingAsync(createInjector(), async (i) => {
+        i.bind(HttpAuthenticationSettings, () => ({
+          ...defaultHttpAuthenticationSettings(),
+          userCacheTtlMs: 0,
+        }))
+        const cache = i.get(UserResolutionCache)
+        expect(() => cache.invalidateByUser('alice')).not.toThrow()
+        expect(cache.size).toBe(0)
+      })
+    })
+  })
+})
+
+describe('resolveUserCacheKey', () => {
+  it('returns the first non-null key from the configured providers', () => {
+    const settings = {
+      ...defaultHttpAuthenticationSettings(),
+      authenticationProviders: [
+        { name: 'first', authenticate: async () => null, getCacheKey: () => null },
+        { name: 'second', authenticate: async () => null, getCacheKey: () => 'cookie:matched' },
+        { name: 'third', authenticate: async () => null, getCacheKey: () => 'jwt:not-reached' },
+      ],
+    }
+    expect(resolveUserCacheKey(settings, { headers: {} })).toBe('cookie:matched')
+  })
+
+  it('returns null when every provider opts out', () => {
+    const settings = {
+      ...defaultHttpAuthenticationSettings(),
+      authenticationProviders: [
+        { name: 'a', authenticate: async () => null },
+        { name: 'b', authenticate: async () => null, getCacheKey: () => null },
+      ],
+    }
+    expect(resolveUserCacheKey(settings, { headers: {} })).toBeNull()
+  })
+})