layercache 1.3.4 → 2.0.0

package/benchmarks/queue-amplification.ts

@@ -1,230 +0,0 @@
-import { Redis } from 'ioredis'
-import { CacheStack, MemoryLayer, RedisLayer, RedisSingleFlightCoordinator } from '../src'
-import { buildConcurrencyLabel, summarizeQueueAmplification } from './queue-amplification-utils'
-import { REDIS_PORT, ensureRedisContainer, stopRedisContainer, unpauseRedisContainer, waitForRedisReady } from './redis'
-import { startRedisLatencyProxy } from './redis-latency-proxy'
-import { type CountedFetcher, createCountedFetcher, runConcurrent } from './scenario-utils'
-import { buildDelayLabel } from './slow-redis-utils'
-
-const LATENCY_LEVELS = [0, 100, 500] as const
-const CONCURRENCY_LEVELS = [1, 10, 50, 100, 250, 500] as const
-const TIMEOUT_MS = 30_000
-
-interface QueueAmplificationResult {
-  label: string
-  count: number
-  minMs: number
-  maxMs: number
-  avgMs: number
-  medianMs: number
-  p95Ms: number
-  delayLabel: string
-  scenario: string
-  concurrency: number
-  concurrencyLabel: string
-  totalWallClockMs: number
-  amplificationVsSingle: number
-  linearityRatio: number
-}
-
-interface BenchmarkCacheContext {
-  cache: CacheStack
-  memory: MemoryLayer
-  originFetcher: CountedFetcher<[], { source: string; warmedAt: number }>
-}
-
-function round(value: number): number {
-  return Number(value.toFixed(3))
-}
-
-function createBenchmarkRedis(port: number): Redis {
-  const client = new Redis({
-    host: '127.0.0.1',
-    port,
-    lazyConnect: true,
-    maxRetriesPerRequest: 1,
-    connectTimeout: 6_000,
-    enableOfflineQueue: false,
-    autoResendUnfulfilledCommands: false,
-    retryStrategy: () => null
-  })
-
-  client.on('error', () => {})
-  return client
-}
-
-async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
-  return Promise.race([
-    promise,
-    new Promise<T>((_, reject) => {
-      setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs)
-    })
-  ])
-}
-
-function createLayeredCache(redis: Redis, prefix: string, gracefulDegradation: boolean): BenchmarkCacheContext {
-  const memory = new MemoryLayer({ ttl: 60, maxSize: 50 })
-  const originFetcher = createCountedFetcher(async () => ({
-    source: 'origin',
-    warmedAt: Date.now()
-  }))
-
-  return {
-    memory,
-    originFetcher,
-    cache: new CacheStack([memory, new RedisLayer({ client: redis, ttl: 300, prefix: `${prefix}:cache:` })], {
-      stampedePrevention: true,
-      ...(gracefulDegradation ? { gracefulDegradation: { retryAfterMs: 10_000 } } : {}),
-      singleFlightCoordinator: new RedisSingleFlightCoordinator({
-        client: redis,
-        prefix: `${prefix}:sf:`
-      })
-    })
-  }
-}
-
-async function warmCache(context: BenchmarkCacheContext, key: string): Promise<void> {
-  await context.cache.get(key, () => context.originFetcher.run(), { ttl: 60 })
-}
-
-async function measureBatch(
-  context: BenchmarkCacheContext,
-  key: string,
-  delayLabel: string,
-  scenario: string,
-  concurrency: number,
-  baselineWallClockMs: number
-): Promise<QueueAmplificationResult> {
-  await context.memory.clear()
-
-  const originCountBefore = context.originFetcher.getCount()
-  const batchStartedAt = process.hrtime.bigint()
-  const requestLatenciesMs = await runConcurrent(concurrency, async () => {
-    const requestStartedAt = process.hrtime.bigint()
-    await withTimeout(
-      context.cache.get(key, () => context.originFetcher.run(), { ttl: 60 }),
-      TIMEOUT_MS,
-      `${delayLabel} ${scenario} ${buildConcurrencyLabel(concurrency)}`
-    )
-
-    return Number(process.hrtime.bigint() - requestStartedAt) / 1_000_000
-  })
-  const totalWallClockMs = Number(process.hrtime.bigint() - batchStartedAt) / 1_000_000
-
-  const originFetchCount = context.originFetcher.getCount() - originCountBefore
-  if (originFetchCount !== 0) {
-    throw new Error(
-      `${delayLabel} ${scenario} ${buildConcurrencyLabel(concurrency)} unexpectedly fetched origin ${originFetchCount} times`
-    )
-  }
-
-  return summarizeQueueAmplification({
-    delayLabel,
-    scenario,
-    concurrency,
-    totalWallClockMs,
-    requestLatenciesMs,
-    baselineWallClockMs
-  })
-}
-
-async function runDelayBenchmarks(delayMs: number): Promise<QueueAmplificationResult[]> {
-  const delayLabel = buildDelayLabel(delayMs)
-  const proxy = await startRedisLatencyProxy(REDIS_PORT)
-  proxy.setLatencyMs(delayMs)
-
-  const strictRedis = createBenchmarkRedis(proxy.port)
-  const gracefulRedis = createBenchmarkRedis(proxy.port)
-
-  await Promise.all([strictRedis.connect(), gracefulRedis.connect()])
-  await Promise.all([strictRedis.ping(), gracefulRedis.ping()])
-
-  const strict = createLayeredCache(strictRedis, `queue:${delayMs}:strict:${Date.now()}`, false)
-  const graceful = createLayeredCache(gracefulRedis, `queue:${delayMs}:graceful:${Date.now()}`, true)
-
-  try {
-    const strictKey = `queue:strict:${delayMs}`
-    const gracefulKey = `queue:graceful:${delayMs}`
-
-    await warmCache(strict, strictKey)
-    await warmCache(graceful, gracefulKey)
-
-    const scenarios = [
-      { scenario: 'strict-l2-hit', context: strict, key: strictKey },
-      { scenario: 'graceful-l2-hit', context: graceful, key: gracefulKey }
-    ]
-
-    const results: QueueAmplificationResult[] = []
-
-    for (const { scenario, context, key } of scenarios) {
-      let baselineWallClockMs = 0
-
-      for (const concurrency of CONCURRENCY_LEVELS) {
-        const effectiveBaseline = baselineWallClockMs || 1
-        const summary = await measureBatch(
-          context,
-          key,
-          delayLabel,
-          scenario,
-          concurrency,
-          concurrency === 1 ? effectiveBaseline : baselineWallClockMs
-        )
-
-        if (concurrency === 1) {
-          baselineWallClockMs = summary.totalWallClockMs
-          results.push({
-            ...summary,
-            amplificationVsSingle: 1,
-            linearityRatio: 1
-          })
-          continue
-        }
-
-        results.push(summary)
-      }
-    }
-
-    return results
-  } finally {
-    await strict.cache.disconnect().catch(() => {})
-    await graceful.cache.disconnect().catch(() => {})
-    await strictRedis.quit().catch(() => {})
-    await gracefulRedis.quit().catch(() => {})
-    await proxy.close().catch(() => {})
-  }
-}
-
-async function main(): Promise<void> {
-  await ensureRedisContainer()
-  await waitForRedisReady()
-
-  try {
-    const results: QueueAmplificationResult[] = []
-    for (const delayMs of LATENCY_LEVELS) {
-      results.push(...(await runDelayBenchmarks(delayMs)))
-    }
-
-    console.table(
-      results.map((result) => ({
-        delay: result.delayLabel,
-        scenario: result.scenario,
-        concurrency: result.concurrency,
-        totalWallClockMs: round(result.totalWallClockMs),
-        avgMs: result.avgMs,
-        p95Ms: result.p95Ms,
-        maxMs: result.maxMs,
-        amplificationVsSingle: result.amplificationVsSingle,
-        linearityRatio: result.linearityRatio
-      }))
-    )
-    console.log(JSON.stringify({ type: 'queue-amplification-benchmark', results }, null, 2))
-  } finally {
-    await unpauseRedisContainer().catch(() => {})
-    await stopRedisContainer()
-  }
-}
-
-void main().catch((error) => {
-  console.error(error)
-  process.exitCode = 1
-})

package/benchmarks/redis-latency-proxy.ts

@@ -1,100 +0,0 @@
-import { type Server, type Socket, connect, createServer } from 'node:net'
-
-export interface RedisLatencyProxy {
-  port: number
-  setLatencyMs: (latencyMs: number) => void
-  close: () => Promise<void>
-}
-
-export async function startRedisLatencyProxy(targetPort: number): Promise<RedisLatencyProxy> {
-  let latencyMs = 0
-  const sockets = new Set<Socket>()
-
-  const server = createServer((clientSocket) => {
-    const upstreamSocket = connect({
-      host: '127.0.0.1',
-      port: targetPort
-    })
-
-    sockets.add(clientSocket)
-    sockets.add(upstreamSocket)
-
-    clientSocket.on('error', () => {})
-    upstreamSocket.on('error', () => {})
-    clientSocket.on('close', () => {
-      sockets.delete(clientSocket)
-      if (!upstreamSocket.destroyed) {
-        upstreamSocket.destroy()
-      }
-    })
-    upstreamSocket.on('close', () => {
-      sockets.delete(upstreamSocket)
-      if (!clientSocket.destroyed) {
-        clientSocket.destroy()
-      }
-    })
-
-    clientSocket.on('data', (chunk) => {
-      setTimeout(() => {
-        if (!upstreamSocket.destroyed) {
-          upstreamSocket.write(chunk)
-        }
-      }, latencyMs / 2)
-    })
-
-    upstreamSocket.on('data', (chunk) => {
-      setTimeout(() => {
-        if (!clientSocket.destroyed) {
-          clientSocket.write(chunk)
-        }
-      }, latencyMs / 2)
-    })
-
-    clientSocket.on('end', () => upstreamSocket.end())
-    upstreamSocket.on('end', () => clientSocket.end())
-  })
-
-  await listen(server)
-
-  const address = server.address()
-  if (!address || typeof address === 'string') {
-    throw new Error('Latency proxy failed to acquire a TCP port')
-  }
-
-  return {
-    port: address.port,
-    setLatencyMs(nextLatencyMs: number) {
-      latencyMs = nextLatencyMs
-    },
-    async close() {
-      for (const socket of sockets) {
-        socket.destroy()
-      }
-
-      await closeServer(server)
-    }
-  }
-}
-
-function listen(server: Server): Promise<void> {
-  return new Promise((resolve, reject) => {
-    server.once('error', reject)
-    server.listen(0, '127.0.0.1', () => {
-      server.off('error', reject)
-      resolve()
-    })
-  })
-}
-
-function closeServer(server: Server): Promise<void> {
-  return new Promise((resolve, reject) => {
-    server.close((error) => {
-      if (error) {
-        reject(error)
-        return
-      }
-
-      resolve()
-    })
-  })
-}

package/benchmarks/redis.ts

@@ -1,107 +0,0 @@
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
-import { Redis } from 'ioredis'
-
-const execFileAsync = promisify(execFile)
-
-export const REDIS_CONTAINER_NAME = 'layercache-bench-redis'
-export const REDIS_PORT = 6390
-export const REDIS_IMAGE = 'redis:7-alpine'
-
-async function docker(args: string[]): Promise<string> {
-  const { stdout } = await execFileAsync('docker', args, {
-    cwd: process.cwd(),
-    maxBuffer: 10 * 1024 * 1024
-  })
-
-  return stdout.trim()
-}
-
-async function containerExists(): Promise<boolean> {
-  try {
-    await docker(['inspect', REDIS_CONTAINER_NAME])
-    return true
-  } catch {
-    return false
-  }
-}
-
-async function isContainerRunning(): Promise<boolean> {
-  try {
-    return (await docker(['inspect', '-f', '{{.State.Running}}', REDIS_CONTAINER_NAME])) === 'true'
-  } catch {
-    return false
-  }
-}
-
-async function isContainerPaused(): Promise<boolean> {
-  try {
-    return (await docker(['inspect', '-f', '{{.State.Paused}}', REDIS_CONTAINER_NAME])) === 'true'
-  } catch {
-    return false
-  }
-}
-
-export async function ensureRedisContainer(): Promise<void> {
-  await docker(['version', '--format', '{{.Server.Version}}'])
-
-  if (await isContainerRunning()) {
-    return
-  }
-
-  if (await containerExists()) {
-    await docker(['start', REDIS_CONTAINER_NAME])
-    return
-  }
-
-  await docker(['run', '-d', '--rm', '--name', REDIS_CONTAINER_NAME, '-p', `${REDIS_PORT}:6379`, REDIS_IMAGE])
-}
-
-export async function stopRedisContainer(): Promise<void> {
-  try {
-    await docker(['rm', '-f', REDIS_CONTAINER_NAME])
-  } catch {
-    // Ignore cleanup failures so benchmark reporting can continue.
-  }
-}
-
-export async function pauseRedisContainer(): Promise<void> {
-  if (await isContainerPaused()) {
-    return
-  }
-
-  await docker(['pause', REDIS_CONTAINER_NAME])
-}
-
-export async function unpauseRedisContainer(): Promise<void> {
-  if (!(await isContainerPaused())) {
-    return
-  }
-
-  await docker(['unpause', REDIS_CONTAINER_NAME])
-}
-
-export function createRedisClient(port = REDIS_PORT): Redis {
-  return new Redis(`redis://127.0.0.1:${port}`, {
-    maxRetriesPerRequest: null
-  })
-}
-
-export async function waitForRedisReady(retries = 40): Promise<void> {
-  for (let attempt = 0; attempt < retries; attempt += 1) {
-    try {
-      const response = await docker(['exec', REDIS_CONTAINER_NAME, 'redis-cli', 'ping'])
-      if (response === 'PONG') {
-        return
-      }
-    } catch {
-      // Allow Redis a short time to start up after the container launches.
-    }
-
-    await new Promise((resolve) => {
-      setTimeout(resolve, 250)
-    })
-  }
-
-  throw new Error('Redis did not become ready in time')
-}

package/benchmarks/scenario-utils.ts

@@ -1,38 +0,0 @@
-import { type DurationSummary, summarizeDurations } from './stats'
-
-export interface CountedFetcher<TArgs extends unknown[], TResult> {
-  run: (...args: TArgs) => Promise<TResult>
-  getCount: () => number
-}
-
-export interface ScenarioSummary extends DurationSummary {
-  fetchCount: number
-}
-
-export function createCountedFetcher<TArgs extends unknown[], TResult>(
-  fetcher: (...args: TArgs) => Promise<TResult>
-): CountedFetcher<TArgs, TResult> {
-  let count = 0
-
-  return {
-    run: async (...args: TArgs) => {
-      count += 1
-      return fetcher(...args)
-    },
-    getCount: () => count
-  }
-}
-
-export async function runConcurrent<TResult>(
-  count: number,
-  task: (index: number) => Promise<TResult>
-): Promise<TResult[]> {
-  return Promise.all(Array.from({ length: count }, (_, index) => task(index)))
-}
-
-export function summarizeScenario(label: string, samples: number[], fetchCount: number): ScenarioSummary {
-  return {
-    ...summarizeDurations(label, samples),
-    fetchCount
-  }
-}

package/benchmarks/server.ts

@@ -1,157 +0,0 @@
-import { type IncomingMessage, type Server, type ServerResponse, createServer } from 'node:http'
-
-import type { Redis } from 'ioredis'
-import { CacheStack, MemoryLayer, RedisLayer, RedisSingleFlightCoordinator } from '../src'
-import { resolveBenchmarkFixturePath } from './paths'
-import { createCountedFetcher } from './scenario-utils'
-import { ensureFixtureFile, loadUserFromFixture } from './workload'
-
-export interface BenchmarkServerHandle {
-  port: number
-  close: () => Promise<void>
-  reset: () => Promise<void>
-  warm: () => Promise<void>
-}
-
-const DEFAULT_USER_ID = 4242
-
-function createOriginFetcher(filePath: string) {
-  return createCountedFetcher(async (userId: number) => loadUserFromFixture(filePath, userId))
-}
-
-function respondJson(serverResponse: ServerResponse<IncomingMessage>, statusCode: number, payload: unknown): void {
-  serverResponse.statusCode = statusCode
-  serverResponse.setHeader('content-type', 'application/json')
-  serverResponse.end(JSON.stringify(payload))
-}
-
-export async function startBenchmarkServer(redis: Redis): Promise<BenchmarkServerHandle> {
-  const fixturePath = resolveBenchmarkFixturePath()
-  await ensureFixtureFile(fixturePath)
-
-  const memoryCache = new CacheStack([new MemoryLayer({ ttl: 60, maxSize: 2_000 })], {
-    stampedePrevention: true
-  })
-
-  const layeredCache = new CacheStack(
-    [
-      new MemoryLayer({ ttl: 60, maxSize: 2_000 }),
-      new RedisLayer({ client: redis, ttl: 300, prefix: 'layercache-bench:http:' })
-    ],
-    {
-      stampedePrevention: true,
-      singleFlightCoordinator: new RedisSingleFlightCoordinator({
-        client: redis,
-        prefix: 'layercache-bench:http:single-flight:'
-      })
-    }
-  )
-
-  const gracefulLayeredCache = new CacheStack(
-    [
-      new MemoryLayer({ ttl: 60, maxSize: 2_000 }),
-      new RedisLayer({ client: redis, ttl: 300, prefix: 'layercache-bench:http:graceful:' })
-    ],
-    {
-      stampedePrevention: true,
-      gracefulDegradation: { retryAfterMs: 10_000 },
-      singleFlightCoordinator: new RedisSingleFlightCoordinator({
-        client: redis,
-        prefix: 'layercache-bench:http:graceful:single-flight:'
-      })
-    }
-  )
-
-  const origin = createOriginFetcher(fixturePath)
-
-  const server = createServer(async (request, response) => {
-    const url = new URL(request.url ?? '/', 'http://127.0.0.1')
-    const userId = Number(url.searchParams.get('id') ?? DEFAULT_USER_ID)
-
-    try {
-      if (url.pathname === '/nocache') {
-        const user = await origin.run(userId)
-        respondJson(response, 200, { route: 'nocache', user })
-        return
-      }
-
-      if (url.pathname === '/memory') {
-        const user = await memoryCache.get(`http:user:${userId}`, () => origin.run(userId))
-        respondJson(response, 200, { route: 'memory', user })
-        return
-      }
-
-      if (url.pathname === '/layered') {
-        const user = await layeredCache.get(`http:user:${userId}`, () => origin.run(userId))
-        respondJson(response, 200, { route: 'layered', user })
-        return
-      }
-
-      if (url.pathname === '/layered-graceful') {
-        const user = await gracefulLayeredCache.get(`http:user:${userId}`, () => origin.run(userId))
-        respondJson(response, 200, { route: 'layered-graceful', user })
-        return
-      }
-
-      if (url.pathname === '/health') {
-        respondJson(response, 200, { ok: true, fetchCount: origin.getCount() })
-        return
-      }
-
-      respondJson(response, 404, { error: 'not-found' })
-    } catch (error) {
-      respondJson(response, 500, {
-        error: error instanceof Error ? error.message : String(error)
-      })
-    }
-  })
-
-  await listen(server)
-
-  const address = server.address()
-  if (!address || typeof address === 'string') {
-    throw new Error('Unexpected server address state')
-  }
-
-  return {
-    port: address.port,
-    reset: async () => {
-      await memoryCache.clear()
-      await layeredCache.clear()
-      await gracefulLayeredCache.clear()
-      await redis.flushdb()
-    },
-    warm: async () => {
-      await memoryCache.get(`http:user:${DEFAULT_USER_ID}`, () => origin.run(DEFAULT_USER_ID))
-      await layeredCache.get(`http:user:${DEFAULT_USER_ID}`, () => origin.run(DEFAULT_USER_ID))
-      await gracefulLayeredCache.get(`http:user:${DEFAULT_USER_ID}`, () => origin.run(DEFAULT_USER_ID))
-    },
-    close: async () => {
-      await Promise.all([memoryCache.disconnect(), layeredCache.disconnect(), gracefulLayeredCache.disconnect()])
-      await closeServer(server)
-    }
-  }
-}
-
-function listen(server: Server): Promise<void> {
-  return new Promise((resolve, reject) => {
-    server.once('error', reject)
-    server.listen(0, '127.0.0.1', () => {
-      server.off('error', reject)
-      resolve()
-    })
-  })
-}
-
-function closeServer(server: Server): Promise<void> {
-  return new Promise((resolve, reject) => {
-    server.close((error) => {
-      if (error) {
-        reject(error)
-        return
-      }
-
-      resolve()
-    })
-  })
-}