feat(core): implement generic LRU-TTL cache and integrate with S3 presigned URLs

This commit is contained in:
yiling
2026-06-08 14:52:56 +08:00
parent fab10d14ab
commit ea01d91fa4
4 changed files with 350 additions and 2 deletions
+154
View File
@@ -0,0 +1,154 @@
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { LruTtlCache } from './lru-ttl-cache'
describe('LruTtlCache', () => {
beforeEach(() => {
vi.useFakeTimers()
// performance.now() is also mocked by vi.useFakeTimers() in newer vitest versions
})
afterEach(() => {
vi.useRealTimers()
})
it('should store and retrieve values', () => {
const cache = new LruTtlCache<string, string>(10)
cache.set('key1', 'value1', 1000)
expect(cache.get('key1')).toBe('value1')
})
it('should return undefined for missing keys', () => {
const cache = new LruTtlCache<string, string>(10)
expect(cache.get('nonexistent')).toBeUndefined()
})
it('should evict items based on LRU policy', () => {
const cache = new LruTtlCache<string, string>(2)
cache.set('key1', 'value1', 1000)
cache.set('key2', 'value2', 1000)
// Access key1 to make it most recently used
cache.get('key1')
// Add key3, which should evict key2 (the least recently used)
cache.set('key3', 'value3', 1000)
expect(cache.get('key1')).toBe('value1')
expect(cache.get('key2')).toBeUndefined()
expect(cache.get('key3')).toBe('value3')
})
it('should return undefined for expired items', () => {
const cache = new LruTtlCache<string, string>(10)
cache.set('key1', 'value1', 1000)
vi.advanceTimersByTime(1001)
expect(cache.get('key1')).toBeUndefined()
expect(cache.size).toBe(0)
})
it('should proactively evict expired items on get', () => {
const sampleSize = 5
const cache = new LruTtlCache<string, string>(100, sampleSize)
// Set 10 items, all will expire
for (let i = 0; i < 10; i++) {
cache.set(`key${i}`, `value${i}`, 1000)
}
// Add one item that stays valid
cache.set('valid', 'validValue', 5000)
// Advance time so the 10 items expire
vi.advanceTimersByTime(1001)
// Total size should still be 11 (lazy eviction)
expect(cache.size).toBe(11)
// Call get on the valid item once. It should trigger one evictSample call.
// evictSample will check 5 items.
cache.get('valid')
// Size should now be 11 - 5 = 6
expect(cache.size).toBe(6)
// Call get again, it should evict the remaining 5 expired items
cache.get('valid')
expect(cache.size).toBe(1)
expect(cache.get('valid')).toBe('validValue')
})
it('should loop through the cache with proactive eviction', () => {
// sampleSize = 3 to make sure we cover all items in one go or skip k3 correctly
const cache = new LruTtlCache<string, string>(10, 3)
cache.set('k1', 'v1', 1000)
cache.set('k2', 'v2', 1000)
cache.set('k3', 'v3', 5000)
vi.advanceTimersByTime(1001)
// First get: evicts k1, k2. Checks k3 (not expired).
cache.get('k3')
expect(cache.size).toBe(1)
// Add more items
cache.set('k4', 'v4', 1000)
cache.set('k5', 'v5', 1000)
vi.advanceTimersByTime(1001)
// Second get: evicts k4, k5.
cache.get('k3')
expect(cache.size).toBe(1)
expect(cache.get('k3')).toBe('v3')
})
it('should handle capacity <= 0', () => {
const cache = new LruTtlCache<string, string>(0)
cache.set('key1', 'value1', 1000)
expect(cache.size).toBe(0)
expect(cache.get('key1')).toBeUndefined()
})
it('should handle ttlMs <= 0', () => {
const cache = new LruTtlCache<string, string>(10)
cache.set('key1', 'value1', 0)
expect(cache.size).toBe(0)
expect(cache.get('key1')).toBeUndefined()
cache.set('key2', 'value2', -100)
expect(cache.size).toBe(0)
expect(cache.get('key2')).toBeUndefined()
})
it('should handle manual deletions while the iterator is active', () => {
// This test addresses the user's specific request:
// "add 100 keys to cache, do a evictSample, and remove 99 keys manually, and do evictSample again, see what happen"
const cache = new LruTtlCache<number, number>(200, 10)
// Add 100 keys
for (let i = 0; i < 100; i++) {
cache.set(i, i, 10000)
}
// Initial get to trigger evictSample and initialize the iterator
cache.get(999)
// Remove 99 keys manually (leaving key 99)
for (let i = 0; i < 99; i++) {
cache.delete(i)
}
expect(cache.size).toBe(1)
// Advance time so the remaining key 99 would expire if it was checked
vi.advanceTimersByTime(20000)
// Call get. evictSample should run.
// The iterator was pointing to something that was deleted.
// It should proceed to the next available element (key 99) and evict it.
cache.get(999)
expect(cache.size).toBe(0)
})
})
+117
View File
@@ -0,0 +1,117 @@
export interface CacheEntry<V> {
value: V
expiresAt: number
}
/**
* A generic LRU cache with TTL support and proactive sampling eviction.
*
* It uses a JavaScript Map to maintain insertion order for LRU eviction.
* On every 'get' call, it samples a fixed number of items to check for expiration.
*/
export class LruTtlCache<K, V> {
private cache = new Map<K, CacheEntry<V>>()
private maxCapacity: number
private iterator: IterableIterator<K> | null = null
private sampleSize: number
constructor(capacity: number = 50000, sampleSize: number = 50) {
this.maxCapacity = Math.max(0, capacity)
this.sampleSize = Math.max(1, sampleSize)
}
/**
* Gets a value from the cache.
* Performs proactive eviction of expired items and refreshes the LRU position of the accessed item.
*/
get(key: K): V | undefined {
this.evictSample()
const entry = this.cache.get(key)
if (!entry) return undefined
if (this.now() > entry.expiresAt) {
this.cache.delete(key)
return undefined
}
// LRU: Move to end (most recently used)
this.cache.delete(key)
this.cache.set(key, entry)
return entry.value
}
/**
* Sets a value in the cache with a specified TTL.
* If the cache exceeds capacity, the least recently used item is evicted.
*/
set(key: K, value: V, ttlMs: number): void {
if (this.maxCapacity <= 0 || ttlMs <= 0 || isNaN(ttlMs)) {
this.cache.delete(key)
return
}
if (this.cache.has(key)) {
this.cache.delete(key)
} else if (this.cache.size >= this.maxCapacity) {
// LRU Eviction: Remove the first item (least recently used)
const firstKey = this.cache.keys().next().value
if (firstKey !== undefined) {
this.cache.delete(firstKey)
}
}
this.cache.set(key, { value, expiresAt: this.now() + ttlMs })
}
delete(key: K): boolean {
return this.cache.delete(key)
}
/**
* Proactively evicts a sample of items if they are expired.
* Uses a persistent iterator to ensure all items are eventually checked.
*/
private evictSample(): void {
if (this.cache.size === 0) return
if (!this.iterator) {
this.iterator = this.cache.keys()
}
const now = this.now()
for (let i = 0; i < this.sampleSize; i++) {
let result = this.iterator.next()
if (result.done) {
this.iterator = this.cache.keys()
result = this.iterator.next()
if (result.done) break
}
const key = result.value
const entry = this.cache.get(key)
// If entry was manually deleted, entry will be undefined.
// If it's expired, we delete it.
if (entry && now > entry.expiresAt) {
this.cache.delete(key)
}
}
}
/**
* Monotonic time source to avoid issues with system clock jumps.
*/
private now(): number {
return performance.now()
}
get size(): number {
return this.cache.size
}
clear(): void {
this.cache.clear()
this.iterator = null
}
}
+57
View File
@@ -27,6 +27,14 @@ vi.mock('@aws-sdk/s3-request-presigner', () => {
})
describe('S3Service implementations', () => {
beforeEach(async () => {
const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner')
vi.mocked(getSignedUrl).mockReset()
vi.mocked(getSignedUrl).mockResolvedValue('http://presigned-url')
vi.clearAllMocks()
delete process.env.PRESIGNED_URL_EXPIRES_IN
})
describe('S3StorageService', () => {
it('should correctly build standard endpoints', () => {
const s3 = new S3StorageService('s3.example.com', 'key', 'secret', 'test-bucket', true)
@@ -57,6 +65,55 @@ describe('S3Service implementations', () => {
const url = await s3.presign('bucket', 'key', 'GET')
expect(url).toBe('http://presigned-url')
})
it('should cache GET presign URLs', async () => {
const s3 = new S3StorageService('localhost:9000', 'key', 'secret', 'test-bucket', false)
const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner')
vi.mocked(getSignedUrl).mockClear()
vi.mocked(getSignedUrl).mockResolvedValueOnce('http://presigned-url-1')
vi.mocked(getSignedUrl).mockResolvedValueOnce('http://presigned-url-2')
const url1 = await s3.presign('bucket', 'key', 'GET')
const url2 = await s3.presign('bucket', 'key', 'GET')
expect(url1).toBe('http://presigned-url-1')
expect(url2).toBe('http://presigned-url-1')
expect(vi.mocked(getSignedUrl)).toHaveBeenCalledTimes(1)
})
it('should NOT cache PUT presign URLs', async () => {
const s3 = new S3StorageService('localhost:9000', 'key', 'secret', 'test-bucket', false)
const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner')
vi.mocked(getSignedUrl).mockClear()
vi.mocked(getSignedUrl).mockResolvedValueOnce('http://put-url-1')
vi.mocked(getSignedUrl).mockResolvedValueOnce('http://put-url-2')
const url1 = await s3.presign('bucket', 'key', 'PUT')
const url2 = await s3.presign('bucket', 'key', 'PUT')
expect(url1).toBe('http://put-url-1')
expect(url2).toBe('http://put-url-2')
expect(vi.mocked(getSignedUrl)).toHaveBeenCalledTimes(2)
})
it('should respect PRESIGNED_URL_EXPIRES_IN env', async () => {
process.env.PRESIGNED_URL_EXPIRES_IN = '10'
const s3 = new S3StorageService('localhost:9000', 'key', 'secret', 'test-bucket', false)
const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner')
vi.mocked(getSignedUrl).mockClear()
await s3.presign('bucket', 'key', 'GET')
expect(vi.mocked(getSignedUrl)).toHaveBeenCalledWith(
expect.anything(),
expect.anything(),
expect.objectContaining({ expiresIn: 10 * 3600 }),
)
delete process.env.PRESIGNED_URL_EXPIRES_IN
})
})
describe('LocalStorageService', () => {
+22 -2
View File
@@ -14,6 +14,7 @@ import * as fs from 'fs'
import { readFileSync, statSync } from 'fs'
import * as path from 'path'
import { ulid } from 'ulid'
import { LruTtlCache } from '../cache/lru-ttl-cache'
export function signLocalUrl(bucket: string, key: string): string {
const secret = process.env.BETTER_AUTH_SECRET || 'shumai-local-storage-secret'
@@ -69,6 +70,7 @@ export interface S3Service {
export class S3StorageService implements S3Service {
private client: S3Client
private bucket: string
private presignCache = new LruTtlCache<string, string>(50000)
constructor(
endpoint: string,
@@ -269,6 +271,19 @@ export class S3StorageService implements S3Service {
}
async presign(bucket: string, key: string, method: string): Promise<string> {
const expireHours = parseInt(process.env.PRESIGNED_URL_EXPIRES_IN || '5', 10)
const expiresInSeconds = expireHours * 3600
// Cache time is 2/3 of expire time, rounded to minute
const cacheMinutes = Math.round((expireHours * 60 * 2) / 3)
const cacheTtlMs = cacheMinutes * 60 * 1000
const cacheKey = `${bucket}:${key}`
if (method === 'GET') {
const cached = this.presignCache.get(cacheKey)
if (cached) return cached
}
let command: GetObjectCommand | PutObjectCommand
if (method === 'GET') {
command = new GetObjectCommand({
@@ -284,8 +299,13 @@ export class S3StorageService implements S3Service {
throw new Error(`Invalid method: ${method}`)
}
// 1 hour expiration
return await getSignedUrl(this.client, command, { expiresIn: 3600 })
const url = await getSignedUrl(this.client, command, { expiresIn: expiresInSeconds })
if (method === 'GET') {
this.presignCache.set(cacheKey, url, cacheTtlMs)
}
return url
}
}