mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 14:48:27 +00:00
feat(core): implement generic LRU-TTL cache and integrate with S3 presigned URLs
This commit is contained in:
+154
@@ -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
@@ -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
|
||||
}
|
||||
}
|
||||
@@ -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', () => {
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user