layercache 1.2.9 → 1.3.0

package/benchmarks/memory-pressure.ts

@@ -0,0 +1,144 @@
+import { PerformanceObserver, monitorEventLoopDelay } from 'node:perf_hooks'
+import { CacheStack, MemoryLayer, RedisLayer } from '../src'
+import { createRedisClient, ensureRedisContainer, stopRedisContainer, waitForRedisReady } from './redis'
+import { summarizeGcMetrics } from './slow-redis-utils'
+
+const EVICTION_CAPACITY = 25
+const EVICTION_KEYS = 180
+const EVICTION_PAYLOAD_BYTES = 256 * 1024
+const REVISIT_COUNT = 25
+
+interface MemoryPressureResult {
+  scenario: string
+  maxSize: number
+  uniqueKeys: number
+  evictions: number
+  l1RetainedKeys: number
+  revisitAvgMs: number
+  revisitP95Ms: number
+  revisitOriginFetches: number
+  gcCount: number
+  gcTotalMs: number
+  gcMaxMs: number
+  eventLoopMaxMs: number
+  heapDeltaMb: number
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(3))
+}
+
+function buildLargePayload(bytes: number): { size: number; payload: string } {
+  return {
+    size: bytes,
+    payload: 'p'.repeat(bytes)
+  }
+}
+
+async function measure<TResult>(task: () => Promise<TResult>): Promise<{ durationMs: number; result: TResult }> {
+  const startedAt = process.hrtime.bigint()
+  const result = await task()
+
+  return {
+    durationMs: Number(process.hrtime.bigint() - startedAt) / 1_000_000,
+    result
+  }
+}
+
+async function main(): Promise<void> {
+  await ensureRedisContainer()
+  await waitForRedisReady()
+
+  const redis = createRedisClient()
+  await redis.ping()
+
+  const gcDurations: number[] = []
+  const observer = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      gcDurations.push(entry.duration)
+    }
+  })
+  observer.observe({ entryTypes: ['gc'] })
+
+  const loopDelay = monitorEventLoopDelay({ resolution: 10 })
+  loopDelay.enable()
+
+  let evictions = 0
+  const memoryLayer = new MemoryLayer({
+    ttl: 60,
+    maxSize: EVICTION_CAPACITY,
+    onEvict: () => {
+      evictions += 1
+    }
+  })
+
+  const cache = new CacheStack([
+    memoryLayer,
+    new RedisLayer({ client: redis, ttl: 300, prefix: 'pressure:benchmark:' })
+  ])
+
+  const heapBeforeMb = process.memoryUsage().heapUsed / (1024 * 1024)
+
+  try {
+    await cache.clear()
+    await redis.flushdb()
+
+    for (let index = 0; index < EVICTION_KEYS; index += 1) {
+      await cache.get(`pressure:${index}`, async () => ({ key: index, ...buildLargePayload(EVICTION_PAYLOAD_BYTES) }), {
+        ttl: 60
+      })
+    }
+
+    const retainedKeys = memoryLayer.exportState().length
+    let revisitOriginFetches = 0
+    const revisitSamples: number[] = []
+
+    for (let index = 0; index < REVISIT_COUNT; index += 1) {
+      const { durationMs } = await measure(() =>
+        cache.get(
+          `pressure:${index}`,
+          async () => {
+            revisitOriginFetches += 1
+            return { key: index, ...buildLargePayload(EVICTION_PAYLOAD_BYTES) }
+          },
+          { ttl: 60 }
+        )
+      )
+      revisitSamples.push(durationMs)
+    }
+
+    const sortedSamples = [...revisitSamples].sort((left, right) => left - right)
+    const gcSummary = summarizeGcMetrics(gcDurations)
+    const heapAfterMb = process.memoryUsage().heapUsed / (1024 * 1024)
+
+    const result: MemoryPressureResult = {
+      scenario: 'memory-pressure-eviction',
+      maxSize: EVICTION_CAPACITY,
+      uniqueKeys: EVICTION_KEYS,
+      evictions,
+      l1RetainedKeys: retainedKeys,
+      revisitAvgMs: round(revisitSamples.reduce((sum, sample) => sum + sample, 0) / revisitSamples.length),
+      revisitP95Ms: round(sortedSamples[Math.ceil(sortedSamples.length * 0.95) - 1] ?? 0),
+      revisitOriginFetches,
+      gcCount: gcSummary.gcCount,
+      gcTotalMs: gcSummary.gcTotalMs,
+      gcMaxMs: gcSummary.gcMaxMs,
+      eventLoopMaxMs: round(loopDelay.max / 1_000_000),
+      heapDeltaMb: round(heapAfterMb - heapBeforeMb)
+    }
+
+    console.table([result])
+    console.log(JSON.stringify({ type: 'memory-pressure', result }, null, 2))
+  } finally {
+    loopDelay.disable()
+    observer.disconnect()
+    await cache.disconnect().catch(() => {})
+    await redis.quit().catch(() => {})
+    await stopRedisContainer()
+  }
+}
+
+void main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/benchmarks/multi-process-fanout.ts

@@ -0,0 +1,231 @@
+import { type ChildProcess, fork } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { resolve } from 'node:path'
+import { createRedisClient, ensureRedisContainer, stopRedisContainer, waitForRedisReady } from './redis'
+
+const PROCESS_COUNT = 4
+const BURST_CONCURRENCY_PER_PROCESS = 25
+const FETCH_DELAY_MS = 25
+const COMMAND_TIMEOUT_MS = 200
+
+interface WorkerResponse {
+  id: string
+  ok: boolean
+  result?: unknown
+  error?: unknown
+}
+
+interface MultiProcessInvalidationResult {
+  scenario: string
+  success: boolean
+  observedVersion: number | null
+  latencyMs: number
+}
+
+interface MultiProcessFanoutResult {
+  scenario: string
+  processCount: number
+  concurrencyPerProcess: number
+  totalConcurrency: number
+  latencyMs: number
+  originFetchCount: number
+}
+
+function spawnWorker(): ChildProcess {
+  const workerPath = resolve(process.cwd(), 'benchmarks', 'multi-process-worker.ts')
+  return fork(workerPath, [], {
+    cwd: process.cwd(),
+    execArgv: ['--import', 'tsx'],
+    stdio: ['inherit', 'inherit', 'inherit', 'ipc']
+  })
+}
+
+function sendMessage<T>(worker: ChildProcess, message: Record<string, unknown>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const id = String(message.id)
+
+    const onMessage = (response: WorkerResponse): void => {
+      if (response.id !== id) {
+        return
+      }
+
+      worker.off('message', onMessage)
+      if (!response.ok) {
+        reject(new Error(typeof response.error === 'string' ? response.error : JSON.stringify(response.error)))
+        return
+      }
+
+      resolve(response.result as T)
+    }
+
+    worker.on('message', onMessage)
+    worker.send(message)
+  })
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+async function runInvalidationScenario(
+  workers: ChildProcess[],
+  prefix: string
+): Promise<MultiProcessInvalidationResult> {
+  const busChannel = `${prefix}:bus`
+  const sharedPrefix = `${prefix}:invalidate`
+  await Promise.all(
+    workers.slice(0, 2).map((worker) =>
+      sendMessage(worker, {
+        id: randomUUID(),
+        type: 'init',
+        prefix: sharedPrefix,
+        busChannel,
+        commandTimeoutMs: COMMAND_TIMEOUT_MS
+      })
+    )
+  )
+
+  const writer = workers[0]
+  const reader = workers[1]
+  if (!writer || !reader) {
+    throw new Error('Expected at least two workers for invalidation scenario.')
+  }
+
+  await sendMessage(writer, {
+    id: randomUUID(),
+    type: 'seed',
+    key: 'shared:key',
+    value: { version: 1 }
+  })
+  await sendMessage(reader, {
+    id: randomUUID(),
+    type: 'read',
+    key: 'shared:key'
+  })
+
+  const startedAt = performance.now()
+  await sendMessage(writer, {
+    id: randomUUID(),
+    type: 'seed',
+    key: 'shared:key',
+    value: { version: 2 }
+  })
+
+  let observedVersion: number | null = null
+  for (let attempt = 0; attempt < 40; attempt += 1) {
+    const value =
+      (await sendMessage<{ version: number } | null>(reader, {
+        id: randomUUID(),
+        type: 'read',
+        key: 'shared:key'
+      })) ?? null
+    observedVersion = value?.version ?? null
+    if (observedVersion === 2) {
+      return {
+        scenario: 'multi-process-invalidation',
+        success: true,
+        observedVersion,
+        latencyMs: Number((performance.now() - startedAt).toFixed(3))
+      }
+    }
+
+    await sleep(25)
+  }
+
+  return {
+    scenario: 'multi-process-invalidation',
+    success: false,
+    observedVersion,
+    latencyMs: Number((performance.now() - startedAt).toFixed(3))
+  }
+}
+
+async function runDistributedSingleFlightScenario(
+  workers: ChildProcess[],
+  prefix: string
+): Promise<MultiProcessFanoutResult> {
+  const redis = createRedisClient()
+  const originCounterKey = `${prefix}:origin-count`
+  const sharedPrefix = `${prefix}:fanout`
+  await redis.del(originCounterKey)
+
+  await Promise.all(
+    workers.map((worker) =>
+      sendMessage(worker, {
+        id: randomUUID(),
+        type: 'init',
+        prefix: sharedPrefix,
+        commandTimeoutMs: COMMAND_TIMEOUT_MS
+      }).catch(() => undefined)
+    )
+  )
+
+  const startedAt = performance.now()
+  const startAt = Date.now() + 300
+  await Promise.all(
+    workers.map((worker) =>
+      sendMessage(worker, {
+        id: randomUUID(),
+        type: 'burst',
+        key: 'fanout:key',
+        startAt,
+        concurrency: BURST_CONCURRENCY_PER_PROCESS,
+        originCounterKey,
+        fetchDelayMs: FETCH_DELAY_MS
+      })
+    )
+  )
+  const originFetchCount = Number(await redis.get(originCounterKey)) || 0
+  await redis.quit()
+
+  return {
+    scenario: 'multi-process-distributed-single-flight',
+    processCount: workers.length,
+    concurrencyPerProcess: BURST_CONCURRENCY_PER_PROCESS,
+    totalConcurrency: workers.length * BURST_CONCURRENCY_PER_PROCESS,
+    latencyMs: Number((performance.now() - startedAt).toFixed(3)),
+    originFetchCount
+  }
+}
+
+async function disposeWorkers(workers: ChildProcess[]): Promise<void> {
+  await Promise.all(
+    workers.map(async (worker) => {
+      try {
+        await sendMessage(worker, {
+          id: randomUUID(),
+          type: 'dispose'
+        })
+      } catch {
+        worker.kill('SIGKILL')
+      }
+    })
+  )
+}
+
+async function main(): Promise<void> {
+  await ensureRedisContainer()
+  await waitForRedisReady()
+
+  const invalidationWorkers = Array.from({ length: 2 }, () => spawnWorker())
+  const fanoutWorkers = Array.from({ length: PROCESS_COUNT }, () => spawnWorker())
+  const prefix = `layercache-bench:multiprocess:${Date.now()}`
+
+  try {
+    const invalidationResult = await runInvalidationScenario(invalidationWorkers, prefix)
+    const fanoutResult = await runDistributedSingleFlightScenario(fanoutWorkers, prefix)
+
+    console.table([invalidationResult, fanoutResult])
+    console.log(JSON.stringify({ type: 'multi-process-fanout-benchmark', invalidationResult, fanoutResult }, null, 2))
+  } finally {
+    await disposeWorkers([...invalidationWorkers, ...fanoutWorkers]).catch(() => undefined)
+    await stopRedisContainer()
+  }
+}
+
+void main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/benchmarks/multi-process-worker.ts

@@ -0,0 +1,151 @@
+import { CacheStack, MemoryLayer, RedisInvalidationBus, RedisLayer, RedisSingleFlightCoordinator } from '../src'
+import { createRedisClient } from './redis'
+import { runConcurrent } from './scenario-utils'
+
+interface InitMessage {
+  id: string
+  type: 'init'
+  prefix: string
+  busChannel?: string
+  commandTimeoutMs?: number
+}
+
+interface SeedMessage {
+  id: string
+  type: 'seed'
+  key: string
+  value: unknown
+}
+
+interface ReadMessage {
+  id: string
+  type: 'read'
+  key: string
+}
+
+interface BurstMessage {
+  id: string
+  type: 'burst'
+  key: string
+  startAt: number
+  concurrency: number
+  originCounterKey: string
+  fetchDelayMs: number
+}
+
+interface DisposeMessage {
+  id: string
+  type: 'dispose'
+}
+
+type WorkerMessage = InitMessage | SeedMessage | ReadMessage | BurstMessage | DisposeMessage
+
+let cache: CacheStack | undefined
+const redis = createRedisClient()
+
+function reply(id: string, ok: boolean, result?: unknown, error?: unknown): void {
+  process.send?.({
+    id,
+    ok,
+    result,
+    error: error instanceof Error ? error.message : error
+  })
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms)
+  })
+}
+
+async function ensureInitialized(message: WorkerMessage): Promise<CacheStack> {
+  if (!cache) {
+    throw new Error(`Worker received "${message.type}" before init.`)
+  }
+
+  return cache
+}
+
+process.on('message', async (message: WorkerMessage) => {
+  try {
+    if (message.type === 'init') {
+      if (cache) {
+        throw new Error('Worker already initialized.')
+      }
+
+      const layer = new RedisLayer({
+        client: redis,
+        ttl: 300,
+        prefix: `${message.prefix}:cache:`,
+        commandTimeoutMs: message.commandTimeoutMs
+      })
+      const bus =
+        message.busChannel === undefined
+          ? undefined
+          : new RedisInvalidationBus({
+              publisher: redis,
+              subscriber: redis.duplicate(),
+              channel: message.busChannel
+            })
+
+      cache = new CacheStack([new MemoryLayer({ ttl: 60, maxSize: 1_000 }), layer], {
+        stampedePrevention: true,
+        invalidationBus: bus,
+        broadcastL1Invalidation: bus ? true : undefined,
+        singleFlightCoordinator: new RedisSingleFlightCoordinator({
+          client: redis,
+          prefix: `${message.prefix}:sf:`,
+          commandTimeoutMs: message.commandTimeoutMs
+        })
+      })
+      reply(message.id, true, { initialized: true })
+      return
+    }
+
+    if (message.type === 'dispose') {
+      await cache?.disconnect()
+      await redis.quit()
+      reply(message.id, true, { disposed: true })
+      process.exit(0)
+      return
+    }
+
+    const initializedCache = await ensureInitialized(message)
+
+    if (message.type === 'seed') {
+      await initializedCache.set(message.key, message.value, { ttl: 60 })
+      reply(message.id, true, { seeded: true })
+      return
+    }
+
+    if (message.type === 'read') {
+      const value = await initializedCache.get(message.key)
+      reply(message.id, true, value)
+      return
+    }
+
+    if (message.type === 'burst') {
+      const waitMs = Math.max(0, message.startAt - Date.now())
+      if (waitMs > 0) {
+        await sleep(waitMs)
+      }
+
+      const startedAt = process.hrtime.bigint()
+      await runConcurrent(message.concurrency, async () => {
+        await initializedCache.get(
+          message.key,
+          async () => {
+            await redis.incr(message.originCounterKey)
+            await sleep(message.fetchDelayMs)
+            return { key: message.key, fetchedAt: Date.now() }
+          },
+          { ttl: 60 }
+        )
+      })
+      const durationMs = Number(process.hrtime.bigint() - startedAt) / 1_000_000
+      reply(message.id, true, { durationMs })
+    }
+  } catch (error) {
+    reply(message.id, false, undefined, error)
+  }
+})

package/benchmarks/paths.ts

@@ -0,0 +1,25 @@
+import { join } from 'node:path'
+
+export interface BenchmarkPathOptions {
+  fixturePath?: string
+}
+
+export function buildBenchmarkFixtureCandidates(options: BenchmarkPathOptions = {}): string[] {
+  const candidates = [
+    options.fixturePath,
+    process.env.LAYERCACHE_BENCH_FIXTURE_PATH,
+    '/root/cache-test/data/users.json',
+    join(process.cwd(), 'data', 'users.json')
+  ].filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
+
+  return [...new Set(candidates)]
+}
+
+export function resolveBenchmarkFixturePath(options: BenchmarkPathOptions = {}): string {
+  const [firstCandidate] = buildBenchmarkFixtureCandidates(options)
+  if (!firstCandidate) {
+    throw new Error('Unable to resolve a benchmark fixture path.')
+  }
+
+  return firstCandidate
+}

package/benchmarks/queue-amplification-utils.ts

@@ -0,0 +1,48 @@
+import { type DurationSummary, summarizeDurations } from './stats'
+
+export interface QueueAmplificationSummary extends DurationSummary {
+  delayLabel: string
+  scenario: string
+  concurrency: number
+  concurrencyLabel: string
+  totalWallClockMs: number
+  amplificationVsSingle: number
+  linearityRatio: number
+}
+
+interface SummarizeQueueAmplificationInput {
+  delayLabel: string
+  scenario: string
+  concurrency: number
+  totalWallClockMs: number
+  requestLatenciesMs: number[]
+  baselineWallClockMs: number
+}
+
+function round(value: number): number {
+  return Number(value.toFixed(3))
+}
+
+export function buildConcurrencyLabel(concurrency: number): string {
+  return `x${concurrency}`
+}
+
+export function summarizeQueueAmplification(input: SummarizeQueueAmplificationInput): QueueAmplificationSummary {
+  if (input.baselineWallClockMs <= 0) {
+    throw new Error('baselineWallClockMs must be greater than 0')
+  }
+
+  const concurrencyLabel = buildConcurrencyLabel(input.concurrency)
+  const totalWallClockMs = round(input.totalWallClockMs)
+
+  return {
+    ...summarizeDurations(`${input.delayLabel}-${input.scenario}-${concurrencyLabel}`, input.requestLatenciesMs),
+    delayLabel: input.delayLabel,
+    scenario: input.scenario,
+    concurrency: input.concurrency,
+    concurrencyLabel,
+    totalWallClockMs,
+    amplificationVsSingle: round(totalWallClockMs / input.baselineWallClockMs),
+    linearityRatio: round(totalWallClockMs / (input.baselineWallClockMs * input.concurrency))
+  }
+}