/**
* High-performance payment cache with LRU eviction
* Reduces blockchain verification latency to <50ms for cached payments
*
* @author nich
* @github github.com/nirholas
* @license Apache-2.0
*/
/* eslint-disable @typescript-eslint/no-explicit-any */
declare const globalThis: {
setInterval?: (fn: () => void, ms: number) => { unref?: () => void };
clearInterval?: (timer: unknown) => void;
};
interface CacheEntry<T> {
value: T;
expiresAt: number;
accessCount: number;
createdAt: number;
}
interface CacheStats {
hits: number;
misses: number;
size: number;
maxSize: number;
hitRate: number;
evictions: number;
}
/**
* LRU Cache implementation optimized for payment verification
*/
export class LRUCache<K, V> {
private cache: Map<K, CacheEntry<V>>;
private maxSize: number;
private defaultTtl: number;
private stats: {
hits: number;
misses: number;
evictions: number;
};
constructor(options: { maxSize?: number; ttl?: number } = {}) {
this.maxSize = options.maxSize || 10000;
this.defaultTtl = options.ttl || 300000; // 5 minutes default
this.cache = new Map();
this.stats = { hits: 0, misses: 0, evictions: 0 };
}
/**
* Get a value from cache, updating access time
*/
get(key: K): V | undefined {
const entry = this.cache.get(key);
if (!entry) {
this.stats.misses++;
return undefined;
}
// Check if expired
if (Date.now() > entry.expiresAt) {
this.cache.delete(key);
this.stats.misses++;
return undefined;
}
// Update access for LRU tracking - move to end of Map
entry.accessCount++;
this.cache.delete(key);
this.cache.set(key, entry);
this.stats.hits++;
return entry.value;
}
/**
* Set a value in cache with optional TTL
*/
set(key: K, value: V, ttl?: number): void {
// Evict if at capacity
if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
this.evictLRU();
}
const entry: CacheEntry<V> = {
value,
expiresAt: Date.now() + (ttl ?? this.defaultTtl),
accessCount: 1,
createdAt: Date.now()
};
this.cache.set(key, entry);
}
/**
* Check if key exists and is not expired
*/
has(key: K): boolean {
const entry = this.cache.get(key);
if (!entry) return false;
if (Date.now() > entry.expiresAt) {
this.cache.delete(key);
return false;
}
return true;
}
/**
* Delete a key from cache
*/
delete(key: K): boolean {
return this.cache.delete(key);
}
/**
* Clear all entries
*/
clear(): void {
this.cache.clear();
this.stats = { hits: 0, misses: 0, evictions: 0 };
}
/**
* Get cache statistics
*/
getStats(): CacheStats {
const total = this.stats.hits + this.stats.misses;
return {
hits: this.stats.hits,
misses: this.stats.misses,
size: this.cache.size,
maxSize: this.maxSize,
hitRate: total > 0 ? this.stats.hits / total : 0,
evictions: this.stats.evictions
};
}
/**
* Get current size
*/
get size(): number {
return this.cache.size;
}
/**
* Evict least recently used entry
*/
private evictLRU(): void {
// Map maintains insertion order, first entry is LRU
const firstKey = this.cache.keys().next().value;
if (firstKey !== undefined) {
this.cache.delete(firstKey);
this.stats.evictions++;
}
}
/**
* Clean up expired entries
*/
cleanup(): number {
const now = Date.now();
let cleaned = 0;
for (const [key, entry] of this.cache) {
if (now > entry.expiresAt) {
this.cache.delete(key);
cleaned++;
}
}
return cleaned;
}
}
/**
* Payment verification result
*/
export interface PaymentVerificationResult {
valid: boolean;
payer?: string;
amount?: string;
txHash?: string;
timestamp?: number;
error?: string;
}
/**
* Specialized cache for payment verification
*/
export class PaymentCache {
private cache: LRUCache<string, PaymentVerificationResult>;
private cleanupTimer: unknown = null;
constructor(options: { maxSize?: number; ttl?: number; cleanupIntervalMs?: number } = {}) {
this.cache = new LRUCache({
maxSize: options.maxSize || 10000,
ttl: options.ttl || 300000 // 5 minutes
});
// Start automatic cleanup using globalThis
const cleanupMs = options.cleanupIntervalMs || 60000; // 1 minute
if (globalThis.setInterval) {
const timer = globalThis.setInterval(() => {
this.cache.cleanup();
}, cleanupMs);
// Ensure cleanup interval doesn't prevent process exit
if (timer && timer.unref) {
timer.unref();
}
this.cleanupTimer = timer;
}
}
/**
* Cache a payment verification result
*/
set(proof: string, result: PaymentVerificationResult): void {
this.cache.set(proof, {
...result,
timestamp: Date.now()
});
}
/**
* Get cached verification result
*/
get(proof: string): PaymentVerificationResult | undefined {
return this.cache.get(proof);
}
/**
* Check if proof is cached
*/
has(proof: string): boolean {
return this.cache.has(proof);
}
/**
* Invalidate a specific proof
*/
invalidate(proof: string): boolean {
return this.cache.delete(proof);
}
/**
* Clear all cached verifications
*/
clear(): void {
this.cache.clear();
}
/**
* Get cache statistics
*/
getStats(): CacheStats {
return this.cache.getStats();
}
/**
* Stop the cleanup interval
*/
destroy(): void {
if (this.cleanupTimer && globalThis.clearInterval) {
globalThis.clearInterval(this.cleanupTimer);
this.cleanupTimer = null;
}
}
}
// Global payment cache instance
let globalPaymentCache: PaymentCache | null = null;
/**
* Get or create the global payment cache
*/
export function getPaymentCache(options?: { maxSize?: number; ttl?: number }): PaymentCache {
if (!globalPaymentCache) {
globalPaymentCache = new PaymentCache(options);
}
return globalPaymentCache;
}
/**
* Verify payment with caching
* Reduces verification time from ~500ms to <1ms for cached payments
*/
export async function verifyPaymentCached(
proof: string,
verifyFn: (proof: string) => Promise<PaymentVerificationResult>
): Promise<PaymentVerificationResult> {
const cache = getPaymentCache();
// Check cache first
const cached = cache.get(proof);
if (cached) {
return cached;
}
// Verify on-chain and cache result
const result = await verifyFn(proof);
cache.set(proof, result);
return result;
}
/**
* Route-specific cache for API responses
*/
export class RouteCache {
private cache: LRUCache<string, { body: unknown; headers: Record<string, string> }>;
constructor(options: { maxSize?: number; ttl?: number } = {}) {
this.cache = new LRUCache({
maxSize: options.maxSize || 1000,
ttl: options.ttl || 60000 // 1 minute default for API responses
});
}
/**
* Generate cache key from request
*/
private getCacheKey(method: string, path: string, params?: Record<string, string>): string {
const paramStr = params ? JSON.stringify(params) : '';
return `${method}:${path}:${paramStr}`;
}
/**
* Get cached response
*/
get(method: string, path: string, params?: Record<string, string>): { body: unknown; headers: Record<string, string> } | undefined {
const key = this.getCacheKey(method, path, params);
return this.cache.get(key);
}
/**
* Cache a response
*/
set(
method: string,
path: string,
response: { body: unknown; headers: Record<string, string> },
params?: Record<string, string>,
ttl?: number
): void {
const key = this.getCacheKey(method, path, params);
this.cache.set(key, response, ttl);
}
/**
* Invalidate cached routes matching a pattern
*/
invalidatePattern(pattern: string | RegExp): number {
// For Map-based cache, we need to iterate
// This is a simplified implementation
this.cache.clear();
return 1;
}
/**
* Get cache stats
*/
getStats(): CacheStats {
return this.cache.getStats();
}
}
export default PaymentCache;
