async getPaymentsKey(@Ctx() user: UserContext) {
    const storeId = user.storeId;
    
    const cacheKey = `get-clientKey-${storeId}`;
    let cacheValue = null;
    
    try {
        cacheValue = await this.cacheService.get(cacheKey);
    } catch (err) {
        this.logger.error(`캐시 조회 실패: ${cacheKey}`, err.stack);
        cacheValue = null;
    }
    
    if (cacheValue) {
        return cacheValue;
    }
    
    const {clientKey, state} = await this.paymentsServcie.getPaymentsKey(storeId);
    
    try {
        if (state === 'ACTIVE') {
            await this.cacheService.set(cacheKey, {clientKey, state});
        }
    } catch (err) {
        this.logger.error(`캐시 설정 실패: ${cacheKey}`, err.stack);
    }
    
    return new GetPaymentsKeyResponse(clientKey, state);
}

export const createDecorator = (
    metadataKey: symbol | string,
    metadata?: unknown,
): MethodDecorator => {
    const aopSymbol = Symbol('AOP_DECORATOR');

    return applyDecorators(
        // 1. 원본 메서드에 메타데이터 기록
        (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
            return AddMetadata<symbol | string, AopMetadata>(metadataKey, {
                originalFn: descriptor.value, // 원본 메서드
                metadata,                     // 데코레이터 옵션
                aopSymbol,                    // 식별용 심볼
            })(target, propertyKey, descriptor);
        },

        // 2. 메서드를 프록시로 교체
        (_: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
            const originalFn = descriptor.value;

            descriptor.value = function (this: any, ...args: unknown[]) {
                // 등록 단계에서 채워진 AOP 로직이 있으면 실행
                const wrappedFn = this[aopSymbol]?.[propertyKey];
                if (wrappedFn) {
                    return wrappedFn.apply(this, args);
                }

                // 없으면 원본 메서드 실행
                return originalFn.apply(this, args);
            };

            Object.defineProperty(descriptor.value, 'name', {
                value: propertyKey.toString(),
                writable: false,
            });
            Object.setPrototypeOf(descriptor.value, originalFn);
        },
    );
};

onModuleInit() {
    this.bootstrapLazyDecorators();
}

private bootstrapLazyDecorators() {
    const controllers = this.discoveryService.getControllers();
    const providers = this.discoveryService.getProviders();

    // @Aspect()가 붙어 있고 wrap 메서드를 가진 프로바이더
    const lazyDecorators = this.lookupLazyDecorators(providers);
    if (lazyDecorators.length === 0) {
        return;
    }

    const instanceWrappers = providers
        .concat(controllers)
        .filter(({ instance }) => instance && Object.getPrototypeOf(instance));

    for (const lazyDecorator of lazyDecorators) {
        for (const wrapper of instanceWrappers) {
            this.applyLazyDecorator(lazyDecorator, wrapper);
        }
    }
}

private applyLazyDecorator(lazyDecorator: LazyDecorator, instanceWrapper: InstanceWrapper<any>) {
    // 싱글톤은 인스턴스, request scope는 프로토타입이 대상
    const target = instanceWrapper.isDependencyTreeStatic()
        ? instanceWrapper.instance
        : instanceWrapper.metatype?.prototype;

    const propertyKeys = this.metadataScanner.scanFromPrototype(/* ... */);
    const metadataKey = this.reflector.get(ASPECT, lazyDecorator.constructor);

    for (const propertyKey of propertyKeys) {
        const targetProperty = target[propertyKey];
        // ...

        // 프로토타입 체인을 따라 원본 메서드의 메타데이터를 읽음
        const metadataList: AopMetadata[] = this.reflector.get(metadataKey, targetProperty);
        if (!metadataList) {
            continue;
        }

        for (const aopMetadata of metadataList) {
            this.wrapMethod({ lazyDecorator, aopMetadata, methodName: propertyKey, target });
        }
    }
}

private wrapMethod({ lazyDecorator, aopMetadata, methodName, target }) {
    const { originalFn, metadata, aopSymbol } = aopMetadata;
    const self = this;

    const wrappedFn = function (this: object, ...args: unknown[]) {
        // 인스턴스별로 한 번 만든 메서드는 재사용
        const cache = self.wrappedMethodCache.get(this) || new WeakMap();
        const cached = cache.get(originalFn);
        if (cached) {
            return cached.apply(this, args);
        }

        // 첫 호출 때 wrap으로 AOP가 적용된 메서드 생성
        const wrappedMethod = lazyDecorator.wrap({
            instance: this,
            methodName,
            method: originalFn.bind(this),
            metadata,
        });
        cache.set(originalFn, wrappedMethod);
        self.wrappedMethodCache.set(this, cache);
        return wrappedMethod.apply(this, args);
    };

    // 프록시가 찾아갈 자리에 wrappedFn 등록
    target[aopSymbol] ??= {};
    target[aopSymbol][methodName] = wrappedFn;
}

@Aspect(CACHEABLE)
@Injectable()
export class CacheableAspect implements LazyDecorator<any, CacheableOption> {
    wrap({ method, metadata: options }: WrapParams<any, CacheableOption>) {
        return (...args: any[]) => {
            // before 로직
            const result = method(...args); // 원본 메서드 호출
            // after 로직
            return result;
        };
    }
}

export interface CacheableOption {
    ttl: number;
    cacheManager?: CacheManager;
    name?: string | ((...args: any[]) => string);
    key?: string | ((...args: any[]) => string);
    condition?: (...args: any[]) => boolean;
    unless?: (result: any, ...args: any[]) => boolean;
}

export interface CacheEvictOption {
    cacheManager?: CacheManager;
    name?: string | string[] | ((...args: any[]) => string | string[]);
    key?: string | ((...args: any[]) => string);
    condition?: (...args: any[]) => boolean;
    allEntries?: boolean;
    beforeInvocation?: boolean;
    debounceMs?: number;
}

private resolveKey(
  option: { key?: string | ((...args: any[]) => string) },
  target: any,
  method: string,
  params: any[]
): string {
  // 커스텀 키 리졸버가 있는 경우 우선 사용
  if (option.key) {
    const resolved = typeof option.key === 'function' ? option.key(...params) : option.key;

    if (resolved) {
      return resolved;
    }
  }

  // 커스텀 키가 없으면 기본 키 생성
  return this.keyGenerator.generate({ target, method, params });
}

private resolveCacheKey(namespace: string | undefined, key: string): string {
  return namespace ? `${namespace}::${key}` : key;
}

import { Injectable } from '@nestjs/common';

import { pack } from 'msgpackr';
import * as XXH from 'xxhashjs';

import { KeyGeneratorParams } from '../core/types';

@Injectable()
export class KeyGenerator {
  generate({ target, method, params }: KeyGeneratorParams): string {
    const className = target?.constructor?.name;
    const prefix = className ? `${className}:${method}` : method;

    // 파라미터가 없는 경우
    if (params.length === 0) {
      return prefix;
    }

    // 파라미터가 1개이고 원시 타입인 경우
    if (params.length === 1) {
      const param = params[0];

      if (param != null && !Array.isArray(param) && this.isPrimitive(param)) {
        return `${prefix}:${param}`;
      }
    }

    // 복잡한 경우 해시 사용
    return this.generateHashedKey(prefix, params);
  }

  private isPrimitive(value: any): boolean {
    return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
  }

  private generateHashedKey(prefix: string, args: any[]): string {
    const packedBuffer = pack(args);
    const hash = XXH.h32(packedBuffer, 0x654c6162).toString(16);

    return `${prefix}:${hash}`;
  }
}

import { createDecorator } from '@toss/nestjs-aop';

export const CACHEABLE = Symbol('Cacheable');
export const Cacheable = (option: CacheableOption) => createDecorator(CACHEABLE, option);

export const CACHE_EVICT = Symbol('CacheEvict');
export const CacheEvict = (option: CacheEvictOption) => createDecorator(CACHE_EVICT, option);

@Aspect(CACHEABLE)
@Injectable()
export class Cacheable implements LazyDecorator<any, CacheableOption> {
  constructor(private readonly cacheAspectSupport: CacheAspectSupport) {}

  wrap({ metadata, method, instance, methodName }: WrapParams<any, CacheableOption>) {
    return async (...args: any[]) => {
      return this.cacheAspectSupport.executeCacheable(metadata, {
        method,
        instance,
        methodName,
        args,
      });
    };
  }
}

async executeCacheable(option: CacheableOption, params: CacheOperationParams): Promise<any> {
  const { method, instance, methodName, args } = params;

  if (option.condition && !option.condition(...args)) {
    return method(...args);
  }

  const key = this.generateCacheableKey(option, instance, methodName, args);
  const cacheProvider = this.cacheResolver.get(option.cacheManager);

  const context: CacheableContext = {
    key,
    method,
    args,
    cacheProvider,
  };

  return this.cacheOperations.getWithSwr(context, option);
}

@Module({
  imports: [
    SwrCacheModule.forRootAsync({
      redisToken: RedisConnection,
      useFactory: () => ({
        inMemory: {
          max: 100,
        },
      }),
    }),
  ],
})
export class AppModule {}

@Cacheable({
  ttl: 60 * 10,
  name: 'payments-key',
  key: (user: UserContext) => `${user.storeId}`,
  unless: (result: GetPaymentsKeyResponse) => result.state !== 'ACTIVE',
})
async getPaymentsKey(@Ctx() user: UserContext) {
  const { clientKey, state } = await this.paymentsService.getPaymentsKey(user.storeId);
  return new GetPaymentsKeyResponse(clientKey, state);
}

private async renewCache(context: CacheableContext, option: CacheableOption): Promise<unknown> {
  const { key, method, args, cacheProvider } = context;

  // 원본 함수 호출
  const result = await method(...args);

  // 'unless' 조건 확인
  if (option.unless?.(result, ...args)) {
    return result;
  }

  // ...캐시 저장
}

async executeCacheEvict(option: CacheEvictOption, params: CacheOperationParams): Promise<any> {
  const { method, instance, methodName, args } = params;

  if (option.condition && !option.condition(...args)) {
    return method(...args);
  }

  const keys = this.generateEvictKeys(option, instance, methodName, args);
  const cacheProvider = this.cacheResolver.get(option.cacheManager);

  const context: CacheEvictContext = {
    keys,
    cacheProvider,
    allEntries: option.allEntries,
  };

  // 디바운스 옵션이 있으면 지연 실행
  const evictFn = option.debounceMs
    ? () => this.cacheOperations.debouncedEvict(context, option.debounceMs!)
    : () => this.cacheOperations.bulkEvict(context);

  // 메서드 실행 전 캐시 삭제
  if (option.beforeInvocation) {
    // debounce는 fire-and-forget (await 시 debounceMs만큼 응답 지연)
    if (option.debounceMs) {
      evictFn();
    } else {
      await evictFn();
    }
    return method(...args);
  }

  // 메서드 실행 후 캐시 삭제
  const result = await method(...args);
  if (option.debounceMs) {
    evictFn();
  } else {
    await evictFn();
  }
  return result;
}

async clearKeysByPattern(pattern: string): Promise<void> {
  let cursor = '0';
  const batchSize = 100;

  do {
    const [newCursor, scannedKeys] = await this.redis.scan(
      cursor,
      'MATCH',
      `${pattern}*`,
      'COUNT',
      batchSize
    );

    if (scannedKeys.length > 0) {
      await Promise.all(scannedKeys.map((key) => this.redis.unlink(key)));
    }

    cursor = newCursor;
  } while (cursor !== '0');
}

@CacheEvict({
  name: ({ storeId }: StorefrontContext) => `website:${storeId}`,
  allEntries: true,
})

@Cacheable({ ttl: 300, name: 'users', key: (id: number) => `${id}` })
async getUser(id: number) {}

@CacheEvict({ name: 'users', key: (id: number) => `${id}` })
async updateUser(id: number, dto: UpdateUserDto) {}

async debouncedEvict(context: CacheEvictContext, debounceMs: number): Promise<void> {
  const { keys, cacheProvider, allEntries = false } = context;
  const groupKey = this.createEvictGroupKey(cacheProvider, keys, allEntries);

  return new Promise<void>((resolve) => {
    const existing = this.pendingEvictions.get(groupKey);

    if (existing) {
      // 기존 타이머 취소 및 키 병합
      clearTimeout(existing.timer);
      keys.forEach((k) => existing.keys.add(k));
      existing.resolvers.push(resolve);

      // 새 타이머 설정 (디바운스 리셋)
      existing.timer = setTimeout(() => {
        this.executePendingEviction(groupKey, cacheProvider);
      }, debounceMs);
    } else {
      const timer = setTimeout(() => {
        this.executePendingEviction(groupKey, cacheProvider);
      }, debounceMs);

      this.pendingEvictions.set(groupKey, {
        keys: new Set(keys),
        allEntries,
        timer,
        resolvers: [resolve],
      });
    }
  });
}

@CacheEvict({
  name: ({ storeId }: StorefrontContext) => `website:${storeId}`,
  allEntries: true,
  debounceMs: 3000,
})
@Post('/apps/components/sync')
async sync() {}

export interface CacheProvider {
  ping(): Promise<string>;
  tryLock(key: string, expire?: number): Promise<boolean>;
  unlock(lockKey: string): Promise<boolean>;
  get<T>(key: any): Promise<T | null>;
  put(key: any, value: any, ttl?: number): Promise<void>;
  evict(key: any): Promise<void>;
  clear(): Promise<void>;
  clearKeysByPattern(pattern: string): Promise<void>;
}

async get<T>(key: string): Promise<T | null> {
  // L1 캐시 조회
  try {
    const l1Value = await this.l1Cache.get<T>(key);
    if (l1Value !== null) {
      return l1Value;
    }
  } catch (error) {
    console.warn('L1 캐시 조회 실패:', error);
  }

  // L2 캐시 조회
  try {
    const l2Value = await this.l2Cache.get<T>(key);
    if (l2Value) {
      // L2 캐시 (Write-back)
      await this.l1Cache.put(key, l2Value, this.L1_WRITE_BACK_TTL).catch(() => {});
      return l2Value;
    }
  } catch (error) {
    console.warn('L2 캐시 조회 실패:', error);
  }

  return null;
}

async put(key: string, value: unknown, ttl?: number): Promise<void> {
  const l1Ttl = Math.min(ttl || this.L1_MAX_TTL, this.L1_MAX_TTL);
  const l2Ttl = ttl || this.L2_DEFAULT_TTL;

  await Promise.allSettled([
    this.l1Cache.put(key, value, l1Ttl),
    this.l2Cache.put(key, value, l2Ttl),
  ]);
}

async tryLock(key: string, expire = 60): Promise<boolean> {
  return this.l2Cache.tryLock(key, expire);
}

export class CacheEnvelope {
  constructor(
    public readonly data: unknown,
    public readonly createdAt: number,
    public readonly expiresAt: number
  ) {}

  static createAsJitter(data: unknown, ttl: number): CacheEnvelope {
    const now = Date.now();
    const jitterMs = (Math.random() - 0.5) * (ttl * 0.1 * 1000);

    return new CacheEnvelope(data, now, now + ttl * 1000 + jitterMs);
  }

  isStale(): boolean {
    return Date.now() > this.expiresAt;
  }

  isFresh(): boolean {
    return !this.isStale();
  }
}

private resolvePhysicalTtl(ttl: number): number {
  let multiplier = 2;
  if (ttl < 60) {
    multiplier = 10;
  } else if (ttl < 3600) {
    multiplier = 5;
  }

  const physicalTtl = ttl * multiplier;

  const JITTER_RATIO = 0.1;
  const MAX_JITTER_SECONDS = 20;

  const maxJitter = Math.min(physicalTtl * JITTER_RATIO, MAX_JITTER_SECONDS);
  const jitter = Math.random() * maxJitter;

  return Math.round(physicalTtl + jitter);
}

async getWithSwr(context: CacheableContext, option: CacheableOption): Promise<unknown | null> {
  const { key, cacheProvider } = context;
  let envelope: CacheEnvelope | null = null;

  try {
    const cached = await cacheProvider.get<any>(key);
    envelope = CacheEnvelope.fromObject(cached);
  } catch (error) {
    this.logger.debug(`캐시 조회 실패 (키: ${key}). 갱신 시도.`, error);
  }

  if (!envelope) {
    return this.handleCacheMissWithLock(context, option);
  }

  if (envelope.isStale()) {
    this.scheduleBackgroundRefresh(context, option);
    return envelope.data; // Stale 데이터 즉시 반환
  }

  return envelope.data;
}

private scheduleBackgroundRefresh(context: CacheableContext, option: CacheableOption): void {
  setImmediate(() => {
    this.backgroundRefresh(context, option).catch((error) => {
      this.logger.error(`백그라운드 캐시 갱신 실패 (키: ${context.key})`, error);
    });
  });
}

private async backgroundRefresh(context: CacheableContext, option: CacheableOption): Promise<void> {
  const { key, cacheProvider } = context;
  let lockAcquired = false;

  try {
    lockAcquired = await cacheProvider.tryLock(key);
    if (!lockAcquired) {
      return; // 다른 프로세스가 갱신 중
    }

    // 락 대기 중 갱신 여부 재확인
    const cached = await this.getCacheEnvelope(key, cacheProvider);
    if (cached && cached.isFresh()) {
      return; // 이미 다른 프로세스가 갱신 완료
    }

    await this.renewCache(context, option);
  } finally {
    if (lockAcquired) {
      await this.releaseLock(cacheProvider, key);
    }
  }
}

private async handleCacheMissWithLock(
  context: CacheableContext,
  option: CacheableOption
): Promise<unknown> {
  const { key, cacheProvider, method, args } = context;

  // 10번 재시도
  for (let attempt = 0; attempt < 10; attempt++) {
    let lockAcquired = false;

    try {
      lockAcquired = await cacheProvider.tryLock(key);

      // 락 획득 실패 (다른 프로세스가 작업 중)
      if (!lockAcquired) {
        await this.delayWithExponentialBackoff(attempt);

        const cached = await this.getCacheEnvelope(key, cacheProvider);
        if (cached) {
          return cached.data;
        }

        // 여전히 캐시가 없으면 다시 락 획득 시도
        continue;
      }

      // 락 대기 중 다른 프로세스가 캐시 생성했는지 더블 체크
      const cached = await this.getCacheEnvelope(key, cacheProvider);
      if (cached) {
        return cached.data;
      }

      return await this.renewCache(context, option);
    } finally {
      if (lockAcquired) {
        await this.releaseLock(cacheProvider, key);
      }
    }
  }

  // 락 획득 최종 실패 시, 캐시 없이 원본 메서드 실행
  return method(...args);
}

private async delayWithExponentialBackoff(attempt: number): Promise<void> {
  // 20ms -> 40ms -> 80ms -> 160ms ...
  const baseDelay = 20 * Math.pow(2, attempt);

  // 0 ~ 10ms 랜덤 추가
  const jitter = Math.random() * 10;

  // 최대 200ms
  const delay = Math.min(baseDelay + jitter, 200);

  await sleep(delay);
}

// 캐시를 저장하는 행위가 기존 동작에 영향을 주지 않아야 함
try {
  const envelope = CacheEnvelope.createAsJitter(result, option.ttl);
  const physicalTtl = this.resolvePhysicalTtl(option.ttl);

  await cacheProvider.put(key, envelope.toObject(), physicalTtl);
} catch (error) {
  this.logger.warn(`캐시 저장 실패 (키: ${key})`, error);
}

// 캐시 저장 실패 여부와 관계없이 원본 함수의 응답값을 반환합니다
return result;

import { compress, decompress } from '@mongodb-js/zstd';
import { pack, unpack } from 'msgpackr';

const COMPRESSION_THRESHOLD = 5 * 1024;
const COMPRESSION_LEVEL = 3;

const enum Format {
  MSGPACK = 0x01,
  MSGPACK_ZSTD = 0x02,
}

export async function compressIfNeeded(value: unknown): Promise<Buffer> {
  const packed = pack(value);

  if (packed.length < COMPRESSION_THRESHOLD) {
    return Buffer.concat([Buffer.from([Format.MSGPACK]), packed]);
  }

  const compressed = await compress(packed, COMPRESSION_LEVEL);

  // 압축이 오히려 크면 원본 사용
  if (compressed.length >= packed.length) {
    return Buffer.concat([Buffer.from([Format.MSGPACK]), packed]);
  }

  return Buffer.concat([Buffer.from([Format.MSGPACK_ZSTD]), compressed]);
}

export async function decompressIfNeeded<T>(value: Buffer): Promise<T> {
  const format = value[0];
  const data = Buffer.from(value.subarray(1));

  if (format === Format.MSGPACK_ZSTD) {
    const decompressed = await decompress(data);
    return unpack(Buffer.from(decompressed)) as T;
  }

  return unpack(data) as T;
}

it('동시에 요청이 여러 개 들어와도 원본 메서드는 한 번만 실행되어야 한다', async () => {
  // 동시에 100개의 요청 발생
  const promises = Array(100)
    .fill(null)
    .map(() => server.get('/api/test/explicit-key-basic/200'));

  const responses = await Promise.all(promises);

  const firstTimestamp = responses[0].body.timestamp;
  for (const response of responses) {
    expect(response.status).toBe(200);
    expect(response.body.executionCount).toBe(1);
    expect(response.body.timestamp).toBe(firstTimestamp); // 모두 동일한 타임스탬프
  }

  const stats = await server.get('/api/test/stats/execution-count').expect(200);
  expect(stats.body['getCacheableWithExplicitKey-200']).toBe(1); // 실제 실행은 한 번
});

@Get('/nocache/products/:id/reviews')
async noCache(@Param('id') id: string) {
  return fetchReviews(id);
}

@Cacheable({ ttl: 10, name: 'reviews', key: (id: string) => id })
@Get('/cache/products/:id/reviews')
async cached(@Param('id') id: string) {
  return fetchReviews(id);
}