요청 한 건의 일생 5편 — 캐시와 타임아웃, 에러와 추적으로 파이프라인을 지키는 법

[브라우저 캐시] → [CDN] → [Nginx 캐시] → [앱 메모리 캐시] → [Redis] → [DB 버퍼 풀]
   가장 빠름, 무효화 어려움  ◀────────────────────────────▶  가장 느림, 가장 정확

async function getUserCached(id: number): Promise<UserDto> {
  const key = `user:v1:${id}`;
 
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);                  // 히트: DB 안 감
 
  const user = await userService.getById(id);             // 미스: DB 조회
  const ttl = 300 + Math.floor(Math.random() * 60);       // TTL 지터
  await redis.set(key, JSON.stringify(user), 'EX', ttl);
  return user;
}
 
// 쓰기 시에는 DB 커밋 후 캐시 삭제
async function updateUser(id: number, input: UpdateUserInput) {
  await userRepo.update(id, input);
  await redis.del(`user:v1:${id}`);
}

// 프로세스 내 single-flight: 같은 키에 대한 동시 조회를 하나로 합친다
const inflight = new Map<string, Promise<unknown>>();
 
function singleFlight<T>(key: string, fn: () => Promise<T>): Promise<T> {
  const existing = inflight.get(key);
  if (existing) return existing as Promise<T>;
  const p = fn().finally(() => inflight.delete(key));
  inflight.set(key, p);
  return p;
}

클라이언트 30s > 로드밸런서 25s > Nginx proxy_read 20s > 앱 요청 타임아웃 15s
> 풀 대기 2s + DB statement_timeout 5s

// 흔한 착각: Promise.race로 타임아웃을 걸면 쿼리가 멈춘다?
await Promise.race([pool.query(heavySql), sleep(3000).then(() => { throw new TimeoutError(); })]);

app.get('/api/reports/heavy', asyncHandler(async (req, res) => {
  const controller = new AbortController();
  res.on('close', () => {
    if (!res.writableFinished) controller.abort();   // 응답 완료 전에 연결이 닫힘
  });
 
  const data = await reportService.build({ signal: controller.signal });
  res.json(data);
}));

export class AppError extends Error {
  constructor(
    public readonly status: number,
    public readonly code: string,
    message: string,
    public readonly expose = true,     // 메시지를 클라이언트에 보여도 되는가
  ) {
    super(message);
  }
}
export class NotFoundError extends AppError {
  constructor(msg: string) { super(404, 'NOT_FOUND', msg); }
}
export class ConflictError extends AppError {
  constructor(msg: string) { super(409, 'CONFLICT', msg); }
}

function translatePgError(err: any): Error {
  switch (err?.code) {
    case '23505': return new ConflictError('이미 존재하는 값입니다');       // unique_violation
    case '23503': return new AppError(400, 'INVALID_REFERENCE', '참조 대상이 없습니다'); // foreign_key_violation
    case '57014': return new AppError(503, 'QUERY_TIMEOUT', '요청 처리 시간이 초과되었습니다'); // query_canceled
    case '40001': return new AppError(503, 'RETRYABLE', '잠시 후 다시 시도해주세요');  // serialization_failure
    case '40P01': return new AppError(503, 'RETRYABLE', '잠시 후 다시 시도해주세요');  // deadlock_detected
    default:      return err;
  }
}

export function errorHandler(err: unknown, req: Request, res: Response, _next: NextFunction) {
  if (res.headersSent) {
    // 이미 응답을 쓰기 시작했다면 할 수 있는 건 연결을 끊는 것뿐
    req.socket.destroy();
    return;
  }
 
  if (err instanceof z.ZodError) {
    return res.status(400).json({ code: 'VALIDATION_ERROR', details: err.issues });
  }
 
  if (err instanceof AppError) {
    if (err.status >= 500) req.log.error({ err }, 'app error');
    return res.status(err.status).json({
      code: err.code,
      message: err.expose ? err.message : 'Internal Server Error',
      requestId: req.id,
    });
  }
 
  req.log.error({ err }, 'unhandled error');
  res.status(500).json({ code: 'INTERNAL_ERROR', message: 'Internal Server Error', requestId: req.id });
}

import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
 
type Ctx = { requestId: string; userId?: string };
export const als = new AsyncLocalStorage<Ctx>();
 
export function requestContext(req: Request, res: Response, next: NextFunction) {
  const requestId = (req.headers['x-request-id'] as string) ?? randomUUID(); // Nginx가 준 ID 재사용
  req.id = requestId;
  res.setHeader('X-Request-Id', requestId);
  als.run({ requestId }, next);    // 이후 모든 비동기 호출에서 컨텍스트 접근 가능
}
 
// 어디서든 인자 전달 없이 현재 요청 ID를 꺼낼 수 있다
export const currentRequestId = () => als.getStore()?.requestId;

export function accessLogger(req: Request, res: Response, next: NextFunction) {
  const start = process.hrtime.bigint();
  res.on('finish', () => {
    const ms = Number(process.hrtime.bigint() - start) / 1e6;
    logger.info({
      requestId: req.id,
      method: req.method,
      route: req.route?.path,        // /users/:id 형태 (실제 경로보다 집계에 유리)
      status: res.statusCode,
      durationMs: Math.round(ms),
    });
  });
  next();
}

Trace 7f3c9a  GET /api/users/42                           182ms
├─ middleware: authenticate                                 3ms
├─ redis GET user:v1:42 (miss)                              1ms
├─ pg.pool.connect  (대기)                                 140ms   ← 병목!
├─ pg.query SELECT ... FROM users                           4ms
├─ redis SET user:v1:42                                     1ms
└─ serialize + write                                        1ms